From c0f05c1073d62a459de430e506bdd36b99f238b5 Mon Sep 17 00:00:00 2001 From: hepj Date: Tue, 29 Nov 2022 19:19:12 +0800 Subject: [PATCH] =?UTF-8?q?=E6=9B=B4=E6=96=B0transformer=E4=BB=A3=E7=A0=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PyTorch/NLP/Transformer/.dockerignore | 2 - PyTorch/NLP/Transformer/CONTRIBUTING.md | 30 - PyTorch/NLP/Transformer/Dockerfile | 47 - PyTorch/NLP/Transformer/LICENSE | 31 - PyTorch/NLP/Transformer/NOTICE | 6 - PyTorch/NLP/Transformer/PATENTS | 33 - PyTorch/NLP/Transformer/README.md.old | 563 ----- .../NLP/Transformer/average_valid_loss.png | Bin 18860 -> 0 bytes PyTorch/NLP/Transformer/bleu_relationship.png | Bin 10460 -> 0 bytes .../Transformer/decorrelation_threshold.png | Bin 177274 -> 0 bytes PyTorch/NLP/Transformer/distributed_train.py | 63 - PyTorch/NLP/Transformer/fairseq/__init__.py | 10 - PyTorch/NLP/Transformer/fairseq/criterions.py | 48 - .../NLP/Transformer/fairseq/data/__init__.py | 27 - .../fairseq/data/csrc/make_batches.cpp | 77 - .../Transformer/fairseq/data/data_utils.py | 327 --- .../Transformer/fairseq/data/dictionary.py | 221 -- .../fairseq/data/fairseq_dataset.py | 35 - .../fairseq/data/indexed_dataset.py | 206 -- .../fairseq/data/language_pair_dataset.py | 200 -- .../fairseq/data/token_block_dataset.py | 108 - .../NLP/Transformer/fairseq/ddp_trainer.py | 305 --- .../Transformer/fairseq/distributed_utils.py | 111 - PyTorch/NLP/Transformer/fairseq/log_helper.py | 204 -- PyTorch/NLP/Transformer/fairseq/meters.py | 87 - .../Transformer/fairseq/models/__init__.py | 55 - .../models/fairseq_incremental_decoder.py | 42 - .../fairseq/models/fused_layer_norm.py | 159 -- .../Transformer/fairseq/models/transformer.py | 621 ------ .../Transformer/fairseq/modules/__init__.py | 18 - .../fairseq/modules/adaptive_softmax.py | 138 -- .../Transformer/fairseq/modules/conv_tbc.py | 38 - .../fairseq/modules/grad_multiply.py | 20 - .../modules/learned_positional_embedding.py | 31 - .../fairseq/modules/multihead_attention.py | 460 ---- .../sinusoidal_positional_embedding.py | 82 - .../strided_batched_gemm.cpp | 61 - .../strided_batched_gemm_cuda.cu | 345 --- .../fairseq/multiprocessing_pdb.py | 39 - .../NLP/Transformer/fairseq/optim/__init__.py | 46 - .../NLP/Transformer/fairseq/optim/adagrad.py | 30 - PyTorch/NLP/Transformer/fairseq/optim/adam.py | 54 - .../fairseq/optim/fairseq_optimizer.py | 94 - .../fairseq/optim/lr_scheduler/__init__.py | 39 - .../lr_scheduler/fairseq_lr_scheduler.py | 44 - .../optim/lr_scheduler/fixed_schedule.py | 57 - .../inverse_square_root_schedule.py | 75 - .../lr_scheduler/reduce_lr_on_plateau.py | 46 - PyTorch/NLP/Transformer/fairseq/optim/nag.py | 77 - PyTorch/NLP/Transformer/fairseq/optim/sgd.py | 31 - PyTorch/NLP/Transformer/fairseq/options.py | 342 --- .../fairseq/prefixes/nonbreaking_prefix.en | 135 -- .../Transformer/fairseq/sequence_generator.py | 567 ----- PyTorch/NLP/Transformer/fairseq/tokenizer.py | 300 --- PyTorch/NLP/Transformer/fairseq/utils.py | 316 --- PyTorch/NLP/Transformer/inference.py | 290 --- PyTorch/NLP/Transformer/preprocess.py | 210 -- PyTorch/NLP/Transformer/requirements.txt | 5 - .../scripts/average_checkpoints.py | 137 -- PyTorch/NLP/Transformer/scripts/deployer.py | 123 -- .../NLP/Transformer/scripts/deployer_lib.py | 969 --------- .../NLP/Transformer/scripts/docker/build.sh | 1 - .../NLP/Transformer/scripts/docker/launch.sh | 15 - .../NLP/Transformer/scripts/draw_summary.py | 134 -- .../NLP/Transformer/scripts/export_model.sh | 54 - .../Transformer/scripts/run_DGX1_AMP_8GPU.sh | 57 - .../Transformer/scripts/run_DGX1_FP32_8GPU.sh | 57 - .../scripts/run_DGXA100_AMP_8GPU.sh | 58 - .../scripts/run_DGXA100_TF32_8GPU.sh | 66 - .../Transformer/scripts/run_preprocessing.sh | 35 - .../NLP/Transformer/scripts/run_training.sh | 71 - PyTorch/NLP/Transformer/setup.py | 79 - PyTorch/NLP/Transformer/train.py | 430 ---- PyTorch/NLP/Transformer/transformer.png | Bin 196304 -> 0 bytes .../NLP/new-Transformer/.circleci/config.yml | 171 ++ .../NLP/new-Transformer/.github/CODEOWNERS | 18 + .../new-Transformer/.github/ISSUE_TEMPLATE.md | 3 + .../.github/ISSUE_TEMPLATE/bug_report.md | 43 + .../.github/ISSUE_TEMPLATE/documentation.md | 15 + .../.github/ISSUE_TEMPLATE/feature_request.md | 24 + .../.github/ISSUE_TEMPLATE/how-to-question.md | 33 + .../.github/PULL_REQUEST_TEMPLATE.md | 16 + PyTorch/NLP/new-Transformer/.github/stale.yml | 30 + .../.github/workflows/build.yml | 62 + .../.github/workflows/build_wheels.yml | 49 + PyTorch/NLP/new-Transformer/.gitignore | 141 ++ PyTorch/NLP/new-Transformer/.gitmodules | 4 + PyTorch/NLP/new-Transformer/.isort.cfg | 2 + .../new-Transformer/.pre-commit-config.yaml | 40 + .../NLP/new-Transformer/CODE_OF_CONDUCT.md | 77 + PyTorch/NLP/new-Transformer/CONTRIBUTING.md | 82 + PyTorch/NLP/new-Transformer/LICENSE | 21 + PyTorch/NLP/new-Transformer/README.md | 442 ++++ PyTorch/NLP/new-Transformer/README.md-old | 239 +++ .../README.md-old2} | 0 PyTorch/NLP/new-Transformer/docs/Makefile | 20 + .../docs/_static/theme_overrides.css | 9 + .../docs/command_line_tools.rst | 85 + PyTorch/NLP/new-Transformer/docs/conf.py | 134 ++ .../NLP/new-Transformer/docs/criterions.rst | 31 + PyTorch/NLP/new-Transformer/docs/data.rst | 58 + .../NLP/new-Transformer/docs/docutils.conf | 2 + PyTorch/NLP/new-Transformer/docs/fairseq.gif | Bin 0 -> 2664833 bytes .../NLP/new-Transformer/docs/fairseq_logo.png | Bin 0 -> 73036 bytes .../new-Transformer/docs/getting_started.rst | 216 ++ .../new-Transformer/docs/hydra_integration.md | 284 +++ PyTorch/NLP/new-Transformer/docs/index.rst | 49 + .../NLP/new-Transformer/docs/lr_scheduler.rst | 34 + PyTorch/NLP/new-Transformer/docs/make.bat | 36 + PyTorch/NLP/new-Transformer/docs/models.rst | 104 + PyTorch/NLP/new-Transformer/docs/modules.rst | 9 + PyTorch/NLP/new-Transformer/docs/optim.rst | 38 + PyTorch/NLP/new-Transformer/docs/overview.rst | 74 + .../NLP/new-Transformer/docs/requirements.txt | 2 + PyTorch/NLP/new-Transformer/docs/tasks.rst | 61 + .../docs/tutorial_classifying_names.rst | 415 ++++ .../docs/tutorial_simple_lstm.rst | 518 +++++ PyTorch/NLP/new-Transformer/env.sh | 39 + .../examples/.gitignore | 0 .../examples/translation/README.md | 0 .../examples/translation/prepare-iwslt14.sh | 0 .../translation/prepare-wmt14en2de.sh | 0 .../translation/prepare-wmt14en2fr.sh | 0 .../NLP/new-Transformer/fairseq/__init__.py | 45 + .../fairseq/benchmark/__init__.py | 7 + .../benchmark_multihead_attention.py | 172 ++ .../fairseq/benchmark/dummy_dataset.py | 36 + .../fairseq/benchmark/dummy_lm.py | 83 + .../fairseq/benchmark/dummy_masked_lm.py | 94 + .../fairseq/benchmark/dummy_model.py | 96 + .../fairseq/benchmark/dummy_mt.py | 119 ++ .../NLP/new-Transformer/fairseq/binarizer.py | 381 ++++ .../fairseq/checkpoint_utils.py | 901 ++++++++ .../clib/cuda/ngram_repeat_block_cuda.cpp | 55 + .../cuda/ngram_repeat_block_cuda_kernel.cu | 82 + .../clib/libbase/balanced_assignment.cpp | 109 + .../fairseq/clib/libbleu/libbleu.cpp | 157 ++ .../fairseq/clib/libbleu/module.cpp | 33 + .../fairseq/clib/libnat/edit_dist.cpp | 231 +++ .../fairseq/clib/libnat_cuda/binding.cpp | 67 + .../fairseq/clib/libnat_cuda/edit_dist.cu | 344 +++ .../fairseq/clib/libnat_cuda/edit_dist.h | 25 + .../fairseq/config/__init__.py | 4 + .../fairseq/config/config.yaml | 19 + .../transformer_lm_baevski_gbw.yaml | 36 + .../transformer_lm_baevski_wiki103.yaml | 36 + .../transformer_lm/transformer_lm_big.yaml | 36 + .../transformer_lm/transformer_lm_gbw.yaml | 36 + .../transformer_lm/transformer_lm_gpt.yaml | 36 + .../transformer_lm_gpt2_big.yaml | 36 + .../transformer_lm_gpt2_medium.yaml | 36 + .../transformer_lm_gpt2_small.yaml | 36 + .../transformer_lm_wiki103.yaml | 36 + .../model/wav2vec/vq_wav2vec_gumbel.yaml | 5 + .../config/model/wav2vec2/wav2vec2_base.yaml | 8 + .../config/model/wav2vec2/wav2vec2_large.yaml | 20 + .../fairseq/criterions/__init__.py | 36 + .../fairseq/criterions/adaptive_loss.py | 123 ++ .../fairseq/criterions/composite_loss.py | 100 + .../fairseq/criterions/cross_entropy.py | 90 + .../new-Transformer/fairseq/criterions/ctc.py | 295 +++ .../fairseq/criterions/fairseq_criterion.py | 120 ++ .../fairseq/criterions/fastspeech2_loss.py | 136 ++ .../fairseq/criterions/hubert_criterion.py | 194 ++ .../label_smoothed_cross_entropy.py | 167 ++ ...moothed_cross_entropy_latency_augmented.py | 220 ++ ...l_smoothed_cross_entropy_with_alignment.py | 130 ++ .../label_smoothed_cross_entropy_with_ctc.py | 96 + .../fairseq/criterions/legacy_masked_lm.py | 177 ++ .../fairseq/criterions/masked_lm.py | 98 + .../fairseq/criterions/model_criterion.py | 155 ++ .../fairseq/criterions/nat_loss.py | 180 ++ .../fairseq/criterions/sentence_prediction.py | 141 ++ .../sentence_prediction_adapters.py | 63 + .../fairseq/criterions/sentence_ranking.py | 120 ++ .../criterions/speech_to_speech_criterion.py | 310 +++ .../criterions/speech_ulm_criterion.py | 126 ++ .../fairseq/criterions/tacotron2_loss.py | 226 ++ .../fairseq/criterions/wav2vec_criterion.py | 230 ++ .../new-Transformer/fairseq/data/__init__.py | 130 ++ .../fairseq/data/add_target_dataset.py | 83 + .../fairseq/data/append_token_dataset.py | 41 + .../fairseq/data/audio}/__init__.py | 0 .../fairseq/data/audio/audio_utils.py | 293 +++ .../fairseq/data/audio/data_cfg.py | 299 +++ .../data/audio/feature_transforms/__init__.py | 82 + .../audio/feature_transforms/delta_deltas.py | 37 + .../audio/feature_transforms/global_cmvn.py | 29 + .../audio/feature_transforms/specaugment.py | 131 ++ .../feature_transforms/utterance_cmvn.py | 41 + .../data/audio/frm_text_to_speech_dataset.py | 205 ++ .../fairseq/data/audio/hubert_dataset.py | 344 +++ .../data/audio/multi_modality_dataset.py | 266 +++ .../fairseq/data/audio/raw_audio_dataset.py | 393 ++++ .../data/audio/speech_to_speech_dataset.py | 428 ++++ .../data/audio/speech_to_text_dataset.py | 561 +++++ .../audio/speech_to_text_joint_dataset.py | 359 ++++ .../data/audio/text_to_speech_dataset.py | 248 +++ .../fairseq/data/backtranslation_dataset.py | 165 ++ .../fairseq/data/base_wrapper_dataset.py | 78 + .../fairseq/data/bucket_pad_length_dataset.py | 78 + .../fairseq/data/codedataset.py | 576 +++++ .../fairseq/data/colorize_dataset.py | 25 + .../fairseq/data/concat_dataset.py | 124 ++ .../fairseq/data/concat_sentences_dataset.py | 54 + .../fairseq/data/data_utils.py | 604 ++++++ .../fairseq/data/data_utils_fast.pyx | 178 ++ .../fairseq/data/denoising_dataset.py | 436 ++++ .../fairseq/data/dictionary.py | 401 ++++ .../fairseq/data/encoders/__init__.py | 29 + .../fairseq/data/encoders/byte_bpe.py | 48 + .../fairseq/data/encoders/byte_utils.py | 51 + .../fairseq/data/encoders/bytes.py | 34 + .../fairseq/data/encoders/characters.py | 30 + .../fairseq/data/encoders/fastbpe.py | 36 + .../fairseq/data/encoders/gpt2_bpe.py | 45 + .../fairseq/data/encoders/gpt2_bpe_utils.py | 140 ++ .../fairseq/data/encoders/hf_bert_bpe.py | 50 + .../fairseq/data/encoders/hf_byte_bpe.py | 50 + .../fairseq/data/encoders/moses_tokenizer.py | 49 + .../fairseq/data/encoders/nltk_tokenizer.py | 24 + .../data/encoders/sentencepiece_bpe.py | 65 + .../fairseq/data/encoders/space_tokenizer.py | 21 + .../fairseq/data/encoders/subword_nmt_bpe.py | 54 + .../fairseq/data/encoders/utils.py | 30 + .../fairseq/data/fairseq_dataset.py | 205 ++ .../fairseq/data/fasta_dataset.py | 107 + .../fairseq/data/huffman/__init__.py | 21 + .../fairseq/data/huffman/huffman_coder.py | 267 +++ .../huffman/huffman_mmap_indexed_dataset.py | 287 +++ .../fairseq/data/id_dataset.py | 19 + .../fairseq/data/indexed_dataset.py | 587 ++++++ .../new-Transformer/fairseq/data/iterators.py | 821 ++++++++ .../fairseq/data/language_pair_dataset.py | 477 +++++ .../fairseq/data/legacy/__init__.py | 16 + .../fairseq/data/legacy/block_pair_dataset.py | 311 +++ .../fairseq/data/legacy/masked_lm_dataset.py | 303 +++ .../data/legacy/masked_lm_dictionary.py | 60 + .../fairseq/data/list_dataset.py | 32 + .../fairseq/data/lm_context_window_dataset.py | 97 + .../fairseq/data/lru_cache_dataset.py | 21 + .../fairseq/data/mask_tokens_dataset.py | 220 ++ .../fairseq/data/monolingual_dataset.py | 253 +++ .../fairseq/data/multi_corpus_dataset.py | 256 +++ .../data/multi_corpus_sampled_dataset.py | 152 ++ .../fairseq/data/multilingual/__init__.py | 4 + .../multilingual/multilingual_data_manager.py | 1156 +++++++++++ .../data/multilingual/multilingual_utils.py | 63 + .../multilingual/sampled_multi_dataset.py | 468 +++++ .../sampled_multi_epoch_dataset.py | 199 ++ .../data/multilingual/sampling_method.py | 78 + .../fairseq/data/nested_dictionary_dataset.py | 125 ++ .../new-Transformer/fairseq/data/noising.py | 334 +++ .../fairseq/data/num_samples_dataset.py | 17 + .../fairseq/data/numel_dataset.py | 31 + .../fairseq/data/offset_tokens_dataset.py | 15 + .../fairseq/data/pad_dataset.py | 31 + .../fairseq/data/plasma_utils.py | 197 ++ .../fairseq/data/prepend_dataset.py | 28 + .../fairseq/data/prepend_token_dataset.py | 41 + .../fairseq/data/raw_label_dataset.py | 23 + .../fairseq/data/replace_dataset.py | 36 + .../fairseq/data/resampling_dataset.py | 139 ++ .../fairseq/data/roll_dataset.py | 18 + .../fairseq/data/round_robin_zip_datasets.py | 160 ++ .../fairseq/data/shorten_dataset.py | 78 + .../fairseq/data/sort_dataset.py | 21 + .../fairseq/data/strip_token_dataset.py | 20 + .../fairseq/data/subsample_dataset.py | 72 + .../fairseq/data/text_compressor.py | 58 + .../fairseq/data/token_block_dataset.py | 206 ++ .../fairseq/data/token_block_utils_fast.pyx | 187 ++ .../transform_eos_concat_langpair_dataset.py | 139 ++ .../fairseq/data/transform_eos_dataset.py | 120 ++ .../data/transform_eos_lang_pair_dataset.py | 113 + .../fairseq/dataclass/__init__.py | 13 + .../fairseq/dataclass/configs.py | 1124 ++++++++++ .../fairseq/dataclass/constants.py | 56 + .../fairseq/dataclass/initialize.py | 61 + .../fairseq/dataclass/utils.py | 493 +++++ .../fairseq/distributed/__init__.py | 25 + .../distributed_timeout_wrapper.py | 97 + .../fully_sharded_data_parallel.py | 135 ++ .../legacy_distributed_data_parallel.py | 165 ++ .../distributed/module_proxy_wrapper.py | 56 + .../tpu_distributed_data_parallel.py | 43 + .../fairseq/distributed/utils.py | 808 ++++++++ .../fairseq/file_chunker_utils.py | 84 + .../NLP/new-Transformer/fairseq/file_io.py | 196 ++ .../NLP/new-Transformer/fairseq/file_utils.py | 370 ++++ .../NLP/new-Transformer/fairseq/hub_utils.py | 314 +++ .../fairseq/incremental_decoding_utils.py | 51 + .../fairseq/iterative_refinement_generator.py | 359 ++++ .../fairseq/logging/__init__.py} | 0 .../new-Transformer/fairseq/logging/meters.py | 321 +++ .../fairseq/logging/metrics.py | 316 +++ .../fairseq/logging/progress_bar.py | 582 ++++++ .../fairseq/model_parallel/__init__.py | 6 + .../model_parallel/criterions/__init__.py | 14 + .../vocab_parallel_cross_entropy.py | 87 + .../model_parallel/megatron_trainer.py | 75 + .../fairseq/model_parallel/models/__init__.py | 20 + .../pipeline_parallel_transformer/__init__.py | 6 + .../pipeline_parallel_transformer/layers.py | 600 ++++++ .../pipeline_parallel_transformer/model.py | 789 +++++++ .../model_parallel/models/roberta/__init__.py | 6 + .../model_parallel/models/roberta/model.py | 225 ++ .../model_parallel/models/transformer.py | 121 ++ .../model_parallel/models/transformer_lm.py | 169 ++ .../model_parallel/modules/__init__.py | 17 + .../modules/multihead_attention.py | 349 ++++ .../modules/transformer_layer.py | 78 + .../fairseq/models/__init__.py | 235 +++ .../fairseq/models/bart/__init__.py | 7 + .../fairseq/models/bart/hub_interface.py | 211 ++ .../fairseq/models/bart/model.py | 394 ++++ .../fairseq/models/composite_encoder.py | 57 + .../models/distributed_fairseq_model.py | 147 ++ .../fairseq/models/ema/__init__.py | 20 + .../new-Transformer/fairseq/models/ema/ema.py | 209 ++ .../fairseq/models/fairseq_decoder.py | 104 + .../fairseq/models/fairseq_encoder.py | 92 + .../models/fairseq_incremental_decoder.py | 118 ++ .../fairseq/models/fairseq_model.py | 574 +++++ .../new-Transformer/fairseq/models/fconv.py | 756 +++++++ .../fairseq/models/fconv_lm.py | 136 ++ .../fairseq/models/fconv_self_att.py | 674 ++++++ .../fairseq/models/hubert/__init__.py | 7 + .../fairseq/models/hubert/hubert.py | 570 +++++ .../fairseq/models/hubert/hubert_asr.py | 364 ++++ .../fairseq/models/huggingface/__init__.py | 20 + .../fairseq/models/huggingface/hf_gpt2.py | 168 ++ .../fairseq/models/lightconv.py | 1020 +++++++++ .../fairseq/models/lightconv_lm.py | 306 +++ .../new-Transformer/fairseq/models/lstm.py | 755 +++++++ .../new-Transformer/fairseq/models/lstm_lm.py | 142 ++ .../fairseq/models/masked_lm.py | 404 ++++ .../fairseq/models/model_utils.py | 92 + .../models/multilingual_transformer.py | 229 ++ .../fairseq/models/nat/__init__.py | 13 + .../fairseq/models/nat/cmlm_transformer.py | 162 ++ .../fairseq/models/nat/fairseq_nat_model.py | 172 ++ .../models/nat/insertion_transformer.py | 280 +++ ...iterative_nonautoregressive_transformer.py | 228 ++ .../models/nat/levenshtein_transformer.py | 510 +++++ .../fairseq/models/nat/levenshtein_utils.py | 293 +++ .../fairseq/models/nat/nat_crf_transformer.py | 121 ++ .../models/nat/nonautoregressive_ensembles.py | 254 +++ .../nat/nonautoregressive_transformer.py | 456 ++++ .../fairseq/models/roberta/__init__.py | 11 + .../fairseq/models/roberta/alignment_utils.py | 118 ++ .../fairseq/models/roberta/enc_dec.py | 192 ++ .../fairseq/models/roberta/hub_interface.py | 235 +++ .../fairseq/models/roberta/model.py | 700 +++++++ .../fairseq/models/roberta/model_camembert.py | 50 + .../fairseq/models/roberta/model_gottbert.py | 49 + .../fairseq/models/roberta/model_xlmr.py | 46 + .../models/speech_to_speech/__init__.py | 8 + .../models/speech_to_speech/modules.py | 59 + .../models/speech_to_speech/s2s_conformer.py | 111 + .../speech_to_speech/s2s_transformer.py | 703 +++++++ .../fairseq/models/speech_to_text/__init__.py | 12 + .../fairseq/models/speech_to_text/berard.py | 606 ++++++ .../models/speech_to_text/convtransformer.py | 448 ++++ .../models/speech_to_text/hub_interface.py | 126 ++ .../modules/augmented_memory_attention.py | 488 +++++ .../models/speech_to_text/modules/emformer.py | 1844 +++++++++++++++++ .../speech_to_text/multi_modality_model.py | 49 + .../models/speech_to_text/s2t_conformer.py | 159 ++ .../models/speech_to_text/s2t_transformer.py | 569 +++++ .../speech_to_text/s2t_wav_transformer.py | 485 +++++ .../fairseq/models/speech_to_text/utils.py | 563 +++++ .../models/speech_to_text/xm_transformer.py | 747 +++++++ .../fairseq/models/text_to_speech/__init__.py | 8 + .../models/text_to_speech/codehifigan.py | 95 + .../models/text_to_speech/fastspeech2.py | 448 ++++ .../fairseq/models/text_to_speech/hifigan.py | 179 ++ .../models/text_to_speech/hub_interface.py | 139 ++ .../models/text_to_speech/tacotron2.py | 380 ++++ .../models/text_to_speech/tts_transformer.py | 454 ++++ .../fairseq/models/text_to_speech/vocoder.py | 259 +++ .../fairseq/models/transformer/__init__.py | 50 + .../models/transformer/transformer_base.py | 176 ++ .../models/transformer/transformer_config.py | 333 +++ .../models/transformer/transformer_decoder.py | 480 +++++ .../models/transformer/transformer_encoder.py | 365 ++++ .../models/transformer/transformer_legacy.py | 275 +++ .../fairseq/models/transformer_align.py | 93 + .../models/transformer_from_pretrained_xlm.py | 152 ++ .../fairseq/models/transformer_lm.py | 607 ++++++ .../fairseq/models/transformer_ulm.py | 408 ++++ .../fairseq/models/wav2vec/__init__.py | 8 + .../fairseq/models/wav2vec/utils.py | 21 + .../fairseq/models/wav2vec/wav2vec.py | 630 ++++++ .../fairseq/models/wav2vec/wav2vec2.py | 1284 ++++++++++++ .../fairseq/models/wav2vec/wav2vec2_asr.py | 748 +++++++ .../fairseq/models/xmod/__init__.py | 7 + .../fairseq/models/xmod/hub_interface.py | 51 + .../fairseq/models/xmod/model.py | 742 +++++++ .../models/xmod/transformer_layer_xmod.py | 179 ++ .../fairseq/modules/__init__.py | 104 + .../fairseq/modules/adaptive_input.py | 81 + .../fairseq/modules/adaptive_softmax.py | 268 +++ .../fairseq/modules/base_layer.py | 170 ++ .../fairseq/modules/beamable_mm.py | 18 +- .../modules/character_token_embedder.py | 214 ++ .../fairseq/modules/checkpoint_activations.py | 242 +++ .../fairseq/modules/conformer_layer.py | 299 +++ .../fairseq/modules/conv_tbc.py | 53 + .../fairseq/modules/cross_entropy.py | 59 + .../fairseq/modules/cuda_utils.cu | 202 ++ .../downsampled_multihead_attention.py | 131 +- .../fairseq/modules/dynamic_convolution.py | 310 +++ .../fairseq/modules/dynamic_crf_layer.py | 189 ++ .../modules/dynamicconv_layer/__init__.py | 6 + .../dynamicconv_layer/cuda_function_gen.py | 223 ++ .../dynamicconv_layer/dynamicconv_cuda.cpp | 51 + .../dynamicconv_layer/dynamicconv_cuda.cuh | 50 + .../dynamicconv_cuda_kernel.cu | 176 ++ .../dynamicconv_layer/dynamicconv_layer.py | 227 ++ .../dynamicconv_layer/dynamiconv_cpu.cpp | 29 + .../modules/dynamicconv_layer/setup.py | 23 + .../fairseq/modules/ema_module.py | 150 ++ .../modules/espnet_multihead_attention.py | 254 +++ .../fairseq/modules/fairseq_dropout.py | 51 + .../fairseq/modules/fp32_batch_norm.py | 44 + .../fairseq/modules/fp32_group_norm.py | 25 + .../fairseq/modules/fp32_instance_norm.py | 35 + .../new-Transformer/fairseq/modules/gelu.py | 25 + .../fairseq/modules/grad_multiply.py | 18 + .../modules/gumbel_vector_quantizer.py | 203 ++ .../fairseq/modules/kmeans_attention.py | 744 +++++++ .../modules/kmeans_vector_quantizer.py | 127 ++ .../fairseq/modules/layer_drop.py | 44 + .../fairseq/modules/layer_norm.py | 48 + .../modules/learned_positional_embedding.py | 61 + .../modules/lightconv_layer/__init__.py | 6 + .../lightconv_layer/cuda_function_gen.py | 289 +++ .../lightconv_layer/lightconv_cuda.cpp | 51 + .../lightconv_layer/lightconv_cuda.cuh | 79 + .../lightconv_layer/lightconv_cuda_kernel.cu | 400 ++++ .../lightconv_layer/lightconv_layer.py | 137 ++ .../fairseq/modules/lightconv_layer/setup.py | 23 + .../modules/lightweight_convolution.py | 310 +++ .../fairseq/modules/linearized_convolution.py | 72 +- .../fairseq/modules/location_attention.py | 83 + .../fairseq/modules/lstm_cell_with_zoneout.py | 37 + .../fairseq/modules/multihead_attention.py | 908 ++++++++ .../fairseq/modules/positional_embedding.py | 35 + .../fairseq/modules/positional_encoding.py | 129 ++ .../fairseq/modules/quant_noise.py | 107 + .../fairseq/modules/quantization/__init__.py | 0 .../modules/quantization/pq/__init__.py | 6 + .../fairseq/modules/quantization/pq/em.py | 211 ++ .../quantization/pq/modules/__init__.py | 8 + .../modules/quantization/pq/modules/qconv.py | 115 + .../modules/quantization/pq/modules/qemb.py | 107 + .../quantization/pq/modules/qlinear.py | 71 + .../fairseq/modules/quantization/pq/pq.py | 128 ++ .../fairseq/modules/quantization/pq/utils.py | 376 ++++ .../quantization/quantization_options.py | 44 + .../modules/quantization/scalar/__init__.py | 6 + .../quantization/scalar/modules/__init__.py | 9 + .../quantization/scalar/modules/qact.py | 88 + .../quantization/scalar/modules/qconv.py | 149 ++ .../quantization/scalar/modules/qemb.py | 147 ++ .../quantization/scalar/modules/qlinear.py | 113 + .../modules/quantization/scalar/ops.py | 59 + .../modules/quantization/scalar/utils.py | 80 + .../modules/rotary_positional_embedding.py | 51 + .../fairseq/modules/same_pad.py | 21 + .../fairseq/modules/scalar_bias.py | 8 +- .../sinusoidal_positional_embedding.py | 105 + .../modules/sparse_multihead_attention.py | 140 ++ .../sparse_transformer_sentence_encoder.py | 96 + ...arse_transformer_sentence_encoder_layer.py | 51 + .../fairseq/modules/transformer_layer.py | 563 +++++ .../modules/transformer_sentence_encoder.py | 291 +++ .../transformer_sentence_encoder_layer.py | 139 ++ .../fairseq/modules/transpose_last.py | 20 + .../new-Transformer/fairseq/modules/unfold.py | 19 + .../fairseq/modules/vggblock.py | 116 ++ .../new-Transformer/fairseq/nan_detector.py | 108 + .../fairseq/ngram_repeat_block.py | 120 ++ .../new-Transformer/fairseq/optim/__init__.py | 48 + .../new-Transformer/fairseq/optim/adadelta.py | 47 + .../fairseq/optim/adafactor.py | 268 +++ .../new-Transformer/fairseq/optim/adagrad.py | 40 + .../NLP/new-Transformer/fairseq/optim/adam.py | 239 +++ .../new-Transformer/fairseq/optim/adamax.py | 172 ++ .../fairseq/optim/amp_optimizer.py | 106 + .../NLP/new-Transformer/fairseq/optim/bmuf.py | 200 ++ .../fairseq/optim/composite.py | 190 ++ .../new-Transformer/fairseq/optim/cpu_adam.py | 210 ++ .../fairseq/optim/dynamic_loss_scaler.py | 70 + .../fairseq/optim/fairseq_optimizer.py | 179 ++ .../fairseq/optim/fp16_optimizer.py | 553 +++++ .../fairseq/optim/fused_adam.py | 386 ++++ .../fairseq/optim/fused_lamb.py | 51 + .../fairseq/optim/lr_scheduler/__init__.py | 36 + .../optim/lr_scheduler/cosine_lr_scheduler.py | 147 ++ .../lr_scheduler/fairseq_lr_scheduler.py | 59 + .../optim/lr_scheduler/fixed_schedule.py | 76 + .../inverse_square_root_schedule.py | 85 + .../optim/lr_scheduler/manual_lr_scheduler.py | 121 ++ .../optim/lr_scheduler/pass_through.py | 39 + .../lr_scheduler/polynomial_decay_schedule.py | 89 + .../lr_scheduler/reduce_lr_on_plateau.py | 143 ++ .../optim/lr_scheduler/step_lr_scheduler.py | 85 + .../lr_scheduler/tri_stage_lr_scheduler.py | 175 ++ .../lr_scheduler/triangular_lr_scheduler.py | 83 + .../NLP/new-Transformer/fairseq/optim/nag.py | 111 + .../NLP/new-Transformer/fairseq/optim/sgd.py | 43 + .../new-Transformer/fairseq/optim/shard.py | 58 + .../NLP/new-Transformer/fairseq/options.py | 413 ++++ PyTorch/NLP/new-Transformer/fairseq/pdb.py | 47 + .../fairseq/quantization_utils.py | 143 ++ .../NLP/new-Transformer/fairseq/registry.py | 100 + .../fairseq/scoring/__init__.py | 55 + .../fairseq/scoring/bertscore.py | 44 + .../new-Transformer/fairseq/scoring/bleu.py | 168 ++ .../new-Transformer/fairseq/scoring/chrf.py | 36 + .../new-Transformer/fairseq/scoring/meteor.py | 42 + .../fairseq/scoring/tokenizer.py | 80 + .../new-Transformer/fairseq/scoring/wer.py | 58 + PyTorch/NLP/new-Transformer/fairseq/search.py | 814 ++++++++ .../fairseq/sequence_generator.py | 997 +++++++++ .../fairseq/sequence_scorer.py | 153 ++ .../fairseq/speech_generator.py | 231 +++ .../new-Transformer/fairseq/tasks/__init__.py | 136 ++ .../fairseq/tasks/audio_finetuning.py | 343 +++ .../fairseq/tasks/audio_pretraining.py | 205 ++ .../fairseq/tasks/cross_lingual_lm.py | 191 ++ .../fairseq/tasks/denoising.py | 276 +++ .../fairseq/tasks/fairseq_task.py | 688 ++++++ .../fairseq/tasks/frm_text_to_speech.py | 55 + .../fairseq/tasks/hubert_pretraining.py | 191 ++ .../fairseq/tasks/language_modeling.py | 383 ++++ .../fairseq/tasks/legacy_masked_lm.py | 152 ++ .../fairseq/tasks/masked_lm.py | 270 +++ .../fairseq/tasks/multilingual_denoising.py | 254 +++ .../tasks/multilingual_language_modeling.py | 627 ++++++ .../fairseq/tasks/multilingual_masked_lm.py | 338 +++ .../fairseq/tasks/multilingual_translation.py | 462 +++++ .../fairseq/tasks/online_backtranslation.py | 682 ++++++ .../tasks/semisupervised_translation.py | 485 +++++ .../fairseq/tasks/sentence_prediction.py | 286 +++ .../tasks/sentence_prediction_adapters.py | 56 + .../fairseq/tasks/sentence_ranking.py | 219 ++ .../fairseq/tasks/simultaneous_translation.py | 41 + .../fairseq/tasks/speech_to_speech.py | 520 +++++ .../fairseq/tasks/speech_to_text.py | 186 ++ .../fairseq/tasks/speech_ulm_task.py | 224 ++ .../fairseq/tasks/text_to_speech.py | 501 +++++ .../fairseq/tasks/translation.py | 497 +++++ .../tasks/translation_from_pretrained_bart.py | 132 ++ .../tasks/translation_from_pretrained_xlm.py | 39 + .../fairseq/tasks/translation_lev.py | 195 ++ .../tasks/translation_multi_simple_epoch.py | 441 ++++ .../fairseq/token_generation_constraints.py | 506 +++++ .../NLP/new-Transformer/fairseq/tokenizer.py | 15 + .../NLP/new-Transformer/fairseq/trainer.py | 1593 ++++++++++++++ PyTorch/NLP/new-Transformer/fairseq/utils.py | 842 ++++++++ .../NLP/new-Transformer/fairseq/version.txt | 1 + .../new-Transformer/fairseq_cli/__init__.py | 0 .../new-Transformer/fairseq_cli/eval_lm.py | 347 ++++ .../new-Transformer/fairseq_cli/generate.py | 417 ++++ .../fairseq_cli/hydra_train.py | 91 + .../fairseq_cli/interactive.py | 317 +++ .../new-Transformer/fairseq_cli/preprocess.py | 393 ++++ .../NLP/new-Transformer/fairseq_cli/score.py | 102 + .../NLP/new-Transformer/fairseq_cli/train.py | 564 +++++ .../new-Transformer/fairseq_cli/validate.py | 153 ++ .../new-Transformer/fp16_run_transformer.sh | 20 + .../fp16_run_transformer_4dcus.sh | 23 + .../new-Transformer/fp16_single_process.sh | 42 + PyTorch/NLP/new-Transformer/hubconf.py | 73 + PyTorch/NLP/new-Transformer/pyproject.toml | 3 + PyTorch/NLP/new-Transformer/run-fp16.sh | 28 + PyTorch/NLP/new-Transformer/run.sh | 32 + PyTorch/NLP/new-Transformer/run4-fp16.sh | 23 + PyTorch/NLP/new-Transformer/run4.sh | 23 + .../NLP/new-Transformer/scripts/__init__.py | 0 .../scripts/average_checkpoints.py | 160 ++ .../scripts/build_sym_alignment.py | 60 +- .../scripts/compare_namespaces.py | 46 + .../scripts/compound_split_bleu.sh | 20 + .../scripts/constraints/extract.py | 90 + .../scripts/constraints/validate.py | 34 + .../scripts/convert_dictionary.lua | 34 + .../new-Transformer/scripts/convert_model.lua | 108 + .../NLP/new-Transformer/scripts/count_docs.py | 58 + .../new-Transformer/scripts/read_binarized.py | 48 + PyTorch/NLP/new-Transformer/scripts/rm_pt.py | 141 ++ .../NLP/new-Transformer/scripts/sacrebleu.sh | 27 + .../NLP/new-Transformer/scripts/shard_docs.py | 54 + .../scripts/split_train_valid_docs.py | 86 + .../NLP/new-Transformer/scripts/spm_decode.py | 53 + .../NLP/new-Transformer/scripts/spm_encode.py | 119 ++ .../NLP/new-Transformer/scripts/spm_train.py | 16 + .../NLP/new-Transformer/scripts/test_fsdp.sh | 24 + PyTorch/NLP/new-Transformer/setup.cfg | 4 + PyTorch/NLP/new-Transformer/setup.py | 284 +++ PyTorch/NLP/new-Transformer/single.sh | 44 + PyTorch/NLP/new-Transformer/single_fp16.sh | 43 + PyTorch/NLP/new-Transformer/single_process.sh | 43 + PyTorch/NLP/new-Transformer/train.py | 14 + 607 files changed, 97163 insertions(+), 9993 deletions(-) delete mode 100644 PyTorch/NLP/Transformer/.dockerignore delete mode 100644 PyTorch/NLP/Transformer/CONTRIBUTING.md delete mode 100644 PyTorch/NLP/Transformer/Dockerfile delete mode 100644 PyTorch/NLP/Transformer/LICENSE delete mode 100644 PyTorch/NLP/Transformer/NOTICE delete mode 100644 PyTorch/NLP/Transformer/PATENTS delete mode 100644 PyTorch/NLP/Transformer/README.md.old delete mode 100644 PyTorch/NLP/Transformer/average_valid_loss.png delete mode 100644 PyTorch/NLP/Transformer/bleu_relationship.png delete mode 100644 PyTorch/NLP/Transformer/decorrelation_threshold.png delete mode 100644 PyTorch/NLP/Transformer/distributed_train.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/__init__.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/criterions.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/data/__init__.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/data/csrc/make_batches.cpp delete mode 100644 PyTorch/NLP/Transformer/fairseq/data/data_utils.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/data/dictionary.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/data/fairseq_dataset.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/data/indexed_dataset.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/data/language_pair_dataset.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/data/token_block_dataset.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/ddp_trainer.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/distributed_utils.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/log_helper.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/meters.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/models/__init__.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/models/fairseq_incremental_decoder.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/models/fused_layer_norm.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/models/transformer.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/__init__.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/adaptive_softmax.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/conv_tbc.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/grad_multiply.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/learned_positional_embedding.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/multihead_attention.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/sinusoidal_positional_embedding.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/strided_batched_gemm/strided_batched_gemm.cpp delete mode 100644 PyTorch/NLP/Transformer/fairseq/modules/strided_batched_gemm/strided_batched_gemm_cuda.cu delete mode 100644 PyTorch/NLP/Transformer/fairseq/multiprocessing_pdb.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/__init__.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/adagrad.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/adam.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/fairseq_optimizer.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/__init__.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/fairseq_lr_scheduler.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/fixed_schedule.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/inverse_square_root_schedule.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/reduce_lr_on_plateau.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/nag.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/optim/sgd.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/options.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/prefixes/nonbreaking_prefix.en delete mode 100644 PyTorch/NLP/Transformer/fairseq/sequence_generator.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/tokenizer.py delete mode 100644 PyTorch/NLP/Transformer/fairseq/utils.py delete mode 100644 PyTorch/NLP/Transformer/inference.py delete mode 100644 PyTorch/NLP/Transformer/preprocess.py delete mode 100644 PyTorch/NLP/Transformer/requirements.txt delete mode 100644 PyTorch/NLP/Transformer/scripts/average_checkpoints.py delete mode 100644 PyTorch/NLP/Transformer/scripts/deployer.py delete mode 100644 PyTorch/NLP/Transformer/scripts/deployer_lib.py delete mode 100644 PyTorch/NLP/Transformer/scripts/docker/build.sh delete mode 100644 PyTorch/NLP/Transformer/scripts/docker/launch.sh delete mode 100644 PyTorch/NLP/Transformer/scripts/draw_summary.py delete mode 100644 PyTorch/NLP/Transformer/scripts/export_model.sh delete mode 100644 PyTorch/NLP/Transformer/scripts/run_DGX1_AMP_8GPU.sh delete mode 100644 PyTorch/NLP/Transformer/scripts/run_DGX1_FP32_8GPU.sh delete mode 100644 PyTorch/NLP/Transformer/scripts/run_DGXA100_AMP_8GPU.sh delete mode 100644 PyTorch/NLP/Transformer/scripts/run_DGXA100_TF32_8GPU.sh delete mode 100644 PyTorch/NLP/Transformer/scripts/run_preprocessing.sh delete mode 100644 PyTorch/NLP/Transformer/scripts/run_training.sh delete mode 100644 PyTorch/NLP/Transformer/setup.py delete mode 100644 PyTorch/NLP/Transformer/train.py delete mode 100644 PyTorch/NLP/Transformer/transformer.png create mode 100644 PyTorch/NLP/new-Transformer/.circleci/config.yml create mode 100644 PyTorch/NLP/new-Transformer/.github/CODEOWNERS create mode 100644 PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE.md create mode 100644 PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/bug_report.md create mode 100644 PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/documentation.md create mode 100644 PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/feature_request.md create mode 100644 PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/how-to-question.md create mode 100644 PyTorch/NLP/new-Transformer/.github/PULL_REQUEST_TEMPLATE.md create mode 100644 PyTorch/NLP/new-Transformer/.github/stale.yml create mode 100644 PyTorch/NLP/new-Transformer/.github/workflows/build.yml create mode 100644 PyTorch/NLP/new-Transformer/.github/workflows/build_wheels.yml create mode 100644 PyTorch/NLP/new-Transformer/.gitignore create mode 100644 PyTorch/NLP/new-Transformer/.gitmodules create mode 100644 PyTorch/NLP/new-Transformer/.isort.cfg create mode 100644 PyTorch/NLP/new-Transformer/.pre-commit-config.yaml create mode 100644 PyTorch/NLP/new-Transformer/CODE_OF_CONDUCT.md create mode 100644 PyTorch/NLP/new-Transformer/CONTRIBUTING.md create mode 100644 PyTorch/NLP/new-Transformer/LICENSE create mode 100644 PyTorch/NLP/new-Transformer/README.md create mode 100644 PyTorch/NLP/new-Transformer/README.md-old rename PyTorch/NLP/{Transformer/README.md => new-Transformer/README.md-old2} (100%) create mode 100644 PyTorch/NLP/new-Transformer/docs/Makefile create mode 100644 PyTorch/NLP/new-Transformer/docs/_static/theme_overrides.css create mode 100644 PyTorch/NLP/new-Transformer/docs/command_line_tools.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/conf.py create mode 100644 PyTorch/NLP/new-Transformer/docs/criterions.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/data.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/docutils.conf create mode 100644 PyTorch/NLP/new-Transformer/docs/fairseq.gif create mode 100644 PyTorch/NLP/new-Transformer/docs/fairseq_logo.png create mode 100644 PyTorch/NLP/new-Transformer/docs/getting_started.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/hydra_integration.md create mode 100644 PyTorch/NLP/new-Transformer/docs/index.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/lr_scheduler.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/make.bat create mode 100644 PyTorch/NLP/new-Transformer/docs/models.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/modules.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/optim.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/overview.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/requirements.txt create mode 100644 PyTorch/NLP/new-Transformer/docs/tasks.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/tutorial_classifying_names.rst create mode 100644 PyTorch/NLP/new-Transformer/docs/tutorial_simple_lstm.rst create mode 100644 PyTorch/NLP/new-Transformer/env.sh rename PyTorch/NLP/{Transformer => new-Transformer}/examples/.gitignore (100%) rename PyTorch/NLP/{Transformer => new-Transformer}/examples/translation/README.md (100%) rename PyTorch/NLP/{Transformer => new-Transformer}/examples/translation/prepare-iwslt14.sh (100%) rename PyTorch/NLP/{Transformer => new-Transformer}/examples/translation/prepare-wmt14en2de.sh (100%) rename PyTorch/NLP/{Transformer => new-Transformer}/examples/translation/prepare-wmt14en2fr.sh (100%) create mode 100644 PyTorch/NLP/new-Transformer/fairseq/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/benchmark/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/benchmark/benchmark_multihead_attention.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_masked_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_mt.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/binarizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/checkpoint_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/cuda/ngram_repeat_block_cuda.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/cuda/ngram_repeat_block_cuda_kernel.cu create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/libbase/balanced_assignment.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/libbleu/libbleu.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/libbleu/module.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/libnat/edit_dist.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/binding.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/edit_dist.cu create mode 100644 PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/edit_dist.h create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/config.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_baevski_gbw.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_baevski_wiki103.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_big.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gbw.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_big.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_medium.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_small.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_wiki103.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec/vq_wav2vec_gumbel.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec2/wav2vec2_base.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec2/wav2vec2_large.yaml create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/adaptive_loss.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/composite_loss.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/cross_entropy.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/ctc.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/fairseq_criterion.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/fastspeech2_loss.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/hubert_criterion.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_latency_augmented.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_with_alignment.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_with_ctc.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/legacy_masked_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/masked_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/model_criterion.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/nat_loss.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_prediction.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_prediction_adapters.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_ranking.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/speech_to_speech_criterion.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/speech_ulm_criterion.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/tacotron2_loss.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/criterions/wav2vec_criterion.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/add_target_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/append_token_dataset.py rename PyTorch/NLP/{Transformer/scripts => new-Transformer/fairseq/data/audio}/__init__.py (100%) create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/audio_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/data_cfg.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/delta_deltas.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/global_cmvn.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/specaugment.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/utterance_cmvn.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/frm_text_to_speech_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/hubert_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/multi_modality_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/raw_audio_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_speech_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_text_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_text_joint_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/audio/text_to_speech_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/backtranslation_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/base_wrapper_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/bucket_pad_length_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/codedataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/colorize_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/concat_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/concat_sentences_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/data_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/data_utils_fast.pyx create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/denoising_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/dictionary.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/byte_bpe.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/byte_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/bytes.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/characters.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/fastbpe.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/gpt2_bpe.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/gpt2_bpe_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/hf_bert_bpe.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/hf_byte_bpe.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/moses_tokenizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/nltk_tokenizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/sentencepiece_bpe.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/space_tokenizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/subword_nmt_bpe.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/encoders/utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/fairseq_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/fasta_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/huffman/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/huffman/huffman_coder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/huffman/huffman_mmap_indexed_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/id_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/indexed_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/iterators.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/language_pair_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/legacy/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/legacy/block_pair_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/legacy/masked_lm_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/legacy/masked_lm_dictionary.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/list_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/lm_context_window_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/lru_cache_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/mask_tokens_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/monolingual_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/multi_corpus_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/multi_corpus_sampled_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/multilingual/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/multilingual/multilingual_data_manager.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/multilingual/multilingual_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampled_multi_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampled_multi_epoch_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampling_method.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/nested_dictionary_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/noising.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/num_samples_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/numel_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/offset_tokens_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/pad_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/plasma_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/prepend_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/prepend_token_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/raw_label_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/replace_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/resampling_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/roll_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/round_robin_zip_datasets.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/shorten_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/sort_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/strip_token_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/subsample_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/text_compressor.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/token_block_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/token_block_utils_fast.pyx create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_concat_langpair_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_lang_pair_dataset.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/dataclass/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/dataclass/configs.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/dataclass/constants.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/dataclass/initialize.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/dataclass/utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/distributed/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/distributed/distributed_timeout_wrapper.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/distributed/fully_sharded_data_parallel.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/distributed/legacy_distributed_data_parallel.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/distributed/module_proxy_wrapper.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/distributed/tpu_distributed_data_parallel.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/distributed/utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/file_chunker_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/file_io.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/file_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/hub_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/incremental_decoding_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/iterative_refinement_generator.py rename PyTorch/NLP/{Transformer/.gitmodules => new-Transformer/fairseq/logging/__init__.py} (100%) create mode 100644 PyTorch/NLP/new-Transformer/fairseq/logging/meters.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/logging/metrics.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/logging/progress_bar.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/criterions/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/criterions/vocab_parallel_cross_entropy.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/megatron_trainer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/layers.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/roberta/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/roberta/model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/transformer_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/multihead_attention.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/transformer_layer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/bart/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/bart/hub_interface.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/bart/model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/composite_encoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/distributed_fairseq_model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/ema/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/ema/ema.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/fairseq_decoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/fairseq_encoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/fairseq_incremental_decoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/fairseq_model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/fconv.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/fconv_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/fconv_self_att.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/hubert/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/hubert/hubert.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/hubert/hubert_asr.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/huggingface/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/huggingface/hf_gpt2.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/lightconv.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/lightconv_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/lstm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/lstm_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/masked_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/model_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/multilingual_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/cmlm_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/fairseq_nat_model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/insertion_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/iterative_nonautoregressive_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/levenshtein_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/levenshtein_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/nat_crf_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/nonautoregressive_ensembles.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/nat/nonautoregressive_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/roberta/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/roberta/alignment_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/roberta/enc_dec.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/roberta/hub_interface.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/roberta/model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_camembert.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_gottbert.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_xlmr.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/modules.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/s2s_conformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/s2s_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/berard.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/convtransformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/hub_interface.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/modules/augmented_memory_attention.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/modules/emformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/multi_modality_model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_conformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_wav_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/xm_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/codehifigan.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/fastspeech2.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/hifigan.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/hub_interface.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/tacotron2.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/tts_transformer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/vocoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_base.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_config.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_decoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_encoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_legacy.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer_align.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer_from_pretrained_xlm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/transformer_ulm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec2.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec2_asr.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/xmod/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/xmod/hub_interface.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/xmod/model.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/models/xmod/transformer_layer_xmod.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/adaptive_input.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/adaptive_softmax.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/base_layer.py rename PyTorch/NLP/{Transformer => new-Transformer}/fairseq/modules/beamable_mm.py (71%) create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/character_token_embedder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/checkpoint_activations.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/conformer_layer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/conv_tbc.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/cross_entropy.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/cuda_utils.cu rename PyTorch/NLP/{Transformer => new-Transformer}/fairseq/modules/downsampled_multihead_attention.py (71%) create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamic_convolution.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamic_crf_layer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/cuda_function_gen.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda.cuh create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda_kernel.cu create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_layer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamiconv_cpu.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/setup.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/ema_module.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/espnet_multihead_attention.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/fairseq_dropout.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/fp32_batch_norm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/fp32_group_norm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/fp32_instance_norm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/gelu.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/grad_multiply.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/gumbel_vector_quantizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/kmeans_attention.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/kmeans_vector_quantizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/layer_drop.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/layer_norm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/learned_positional_embedding.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/cuda_function_gen.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda.cpp create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda.cuh create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda_kernel.cu create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_layer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/setup.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lightweight_convolution.py rename PyTorch/NLP/{Transformer => new-Transformer}/fairseq/modules/linearized_convolution.py (60%) create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/location_attention.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/lstm_cell_with_zoneout.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/multihead_attention.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/positional_embedding.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/positional_encoding.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quant_noise.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/em.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qconv.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qemb.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qlinear.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/pq.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/quantization_options.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qact.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qconv.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qemb.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qlinear.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/ops.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/rotary_positional_embedding.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/same_pad.py rename PyTorch/NLP/{Transformer => new-Transformer}/fairseq/modules/scalar_bias.py (71%) create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/sinusoidal_positional_embedding.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/sparse_multihead_attention.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/sparse_transformer_sentence_encoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/sparse_transformer_sentence_encoder_layer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/transformer_layer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/transformer_sentence_encoder.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/transformer_sentence_encoder_layer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/transpose_last.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/unfold.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/modules/vggblock.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/nan_detector.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/ngram_repeat_block.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/adadelta.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/adafactor.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/adagrad.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/adam.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/adamax.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/amp_optimizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/bmuf.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/composite.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/cpu_adam.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/dynamic_loss_scaler.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/fairseq_optimizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/fp16_optimizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/fused_adam.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/fused_lamb.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/cosine_lr_scheduler.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/fairseq_lr_scheduler.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/fixed_schedule.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/inverse_square_root_schedule.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/manual_lr_scheduler.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/pass_through.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/polynomial_decay_schedule.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/reduce_lr_on_plateau.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/step_lr_scheduler.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/tri_stage_lr_scheduler.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/triangular_lr_scheduler.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/nag.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/sgd.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/optim/shard.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/options.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/pdb.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/quantization_utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/registry.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/scoring/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/scoring/bertscore.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/scoring/bleu.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/scoring/chrf.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/scoring/meteor.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/scoring/tokenizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/scoring/wer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/search.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/sequence_generator.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/sequence_scorer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/speech_generator.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/audio_finetuning.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/audio_pretraining.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/cross_lingual_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/denoising.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/fairseq_task.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/frm_text_to_speech.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/hubert_pretraining.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/language_modeling.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/legacy_masked_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/masked_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_denoising.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_language_modeling.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_masked_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_translation.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/online_backtranslation.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/semisupervised_translation.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_prediction.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_prediction_adapters.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_ranking.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/simultaneous_translation.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/speech_to_speech.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/speech_to_text.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/speech_ulm_task.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/text_to_speech.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/translation.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/translation_from_pretrained_bart.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/translation_from_pretrained_xlm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/translation_lev.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tasks/translation_multi_simple_epoch.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/token_generation_constraints.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/tokenizer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/trainer.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/utils.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq/version.txt create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/eval_lm.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/generate.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/hydra_train.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/interactive.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/preprocess.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/score.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/train.py create mode 100644 PyTorch/NLP/new-Transformer/fairseq_cli/validate.py create mode 100644 PyTorch/NLP/new-Transformer/fp16_run_transformer.sh create mode 100644 PyTorch/NLP/new-Transformer/fp16_run_transformer_4dcus.sh create mode 100644 PyTorch/NLP/new-Transformer/fp16_single_process.sh create mode 100644 PyTorch/NLP/new-Transformer/hubconf.py create mode 100644 PyTorch/NLP/new-Transformer/pyproject.toml create mode 100644 PyTorch/NLP/new-Transformer/run-fp16.sh create mode 100644 PyTorch/NLP/new-Transformer/run.sh create mode 100644 PyTorch/NLP/new-Transformer/run4-fp16.sh create mode 100644 PyTorch/NLP/new-Transformer/run4.sh create mode 100644 PyTorch/NLP/new-Transformer/scripts/__init__.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/average_checkpoints.py rename PyTorch/NLP/{Transformer => new-Transformer}/scripts/build_sym_alignment.py (58%) create mode 100644 PyTorch/NLP/new-Transformer/scripts/compare_namespaces.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/compound_split_bleu.sh create mode 100644 PyTorch/NLP/new-Transformer/scripts/constraints/extract.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/constraints/validate.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/convert_dictionary.lua create mode 100644 PyTorch/NLP/new-Transformer/scripts/convert_model.lua create mode 100644 PyTorch/NLP/new-Transformer/scripts/count_docs.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/read_binarized.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/rm_pt.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/sacrebleu.sh create mode 100644 PyTorch/NLP/new-Transformer/scripts/shard_docs.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/split_train_valid_docs.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/spm_decode.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/spm_encode.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/spm_train.py create mode 100644 PyTorch/NLP/new-Transformer/scripts/test_fsdp.sh create mode 100644 PyTorch/NLP/new-Transformer/setup.cfg create mode 100644 PyTorch/NLP/new-Transformer/setup.py create mode 100644 PyTorch/NLP/new-Transformer/single.sh create mode 100644 PyTorch/NLP/new-Transformer/single_fp16.sh create mode 100644 PyTorch/NLP/new-Transformer/single_process.sh create mode 100644 PyTorch/NLP/new-Transformer/train.py diff --git a/PyTorch/NLP/Transformer/.dockerignore b/PyTorch/NLP/Transformer/.dockerignore deleted file mode 100644 index 54c98ee5..00000000 --- a/PyTorch/NLP/Transformer/.dockerignore +++ /dev/null @@ -1,2 +0,0 @@ -results -data diff --git a/PyTorch/NLP/Transformer/CONTRIBUTING.md b/PyTorch/NLP/Transformer/CONTRIBUTING.md deleted file mode 100644 index 5592b2bd..00000000 --- a/PyTorch/NLP/Transformer/CONTRIBUTING.md +++ /dev/null @@ -1,30 +0,0 @@ -# Contributing to FAIR Sequence-to-Sequence Toolkit (PyTorch) -We want to make contributing to this project as easy and transparent as -possible. - -## Pull Requests -We actively welcome your pull requests. - -1. Fork the repo and create your branch from `master`. -2. If you've added code that should be tested, add tests. -3. If you've changed APIs, update the documentation. -4. Ensure the test suite passes. -5. Make sure your code lints. -6. If you haven't already, complete the Contributor License Agreement ("CLA"). - -## Contributor License Agreement ("CLA") -In order to accept your pull request, we need you to submit a CLA. You only need -to do this once to work on any of Facebook's open source projects. - -Complete your CLA here: - -## Issues -We use GitHub issues to track public bugs. Please ensure your description is -clear and has sufficient instructions to be able to reproduce the issue. - -## Coding Style -We try to follow the PEP style guidelines and encourage you to as well. - -## License -By contributing to FAIR Sequence-to-Sequence Toolkit, you agree that your contributions will be licensed -under the LICENSE file in the root directory of this source tree. \ No newline at end of file diff --git a/PyTorch/NLP/Transformer/Dockerfile b/PyTorch/NLP/Transformer/Dockerfile deleted file mode 100644 index 7e87051b..00000000 --- a/PyTorch/NLP/Transformer/Dockerfile +++ /dev/null @@ -1,47 +0,0 @@ -# Copyright (c) 2018, NVIDIA CORPORATION. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -ARG FROM_IMAGE_NAME=nvcr.io/nvidia/pytorch:21.05-py3 -FROM ${FROM_IMAGE_NAME} - -WORKDIR /workspace -#RUN git clone https://github.com/NVIDIA/apex \ -# && cd apex \ -# && pip install -v --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" ./ -# Install Python dependencies -RUN pip install --no-cache-dir \ - sacrebleu \ - sentencepiece -RUN pip install jupyter - -ARG DEBIAN_FRONTEND=noninteractive -RUN apt-get update -RUN apt-get install -y -q cmake pkg-config protobuf-compiler libprotobuf-dev libgoogle-perftools-dev -RUN git clone https://github.com/google/sentencepiece.git /workspace/sentencepiece -RUN cd /workspace/sentencepiece \ - && git checkout d4dd947 \ - && mkdir build \ - && cd build \ - && cmake .. \ - && make -j 8 \ - && make install \ - && ldconfig -v - -ENV PYTHONPATH=/workspace/translation/examples/translation/subword-nmt/ -WORKDIR /workspace/translation -RUN git clone https://github.com/rsennrich/subword-nmt.git /workspace/translation/examples/translation/subword-nmt/ -RUN git clone https://github.com/NVIDIA/cutlass.git && cd cutlass && git checkout ed2ed4d6 && cd .. -COPY . . -RUN pip install -e . -RUN pip install git+https://github.com/NVIDIA/dllogger@v0.1.0#egg=dllogger diff --git a/PyTorch/NLP/Transformer/LICENSE b/PyTorch/NLP/Transformer/LICENSE deleted file mode 100644 index f2ff38d3..00000000 --- a/PyTorch/NLP/Transformer/LICENSE +++ /dev/null @@ -1,31 +0,0 @@ -BSD License - -For fairseq software - -Copyright (c) 2017-present, Facebook, Inc. All rights reserved. -Copyright (c) 2019-present, NVIDIA CORPORATION. All rights reserved. - -Redistribution and use in source and binary forms, with or without modification, -are permitted provided that the following conditions are met: - - * Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - - * Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - * Neither the name Facebook nor the names of its contributors may be used to - endorse or promote products derived from this software without specific - prior written permission. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND -ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR -ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON -ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS -SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/PyTorch/NLP/Transformer/NOTICE b/PyTorch/NLP/Transformer/NOTICE deleted file mode 100644 index 03998da2..00000000 --- a/PyTorch/NLP/Transformer/NOTICE +++ /dev/null @@ -1,6 +0,0 @@ -Transformer PyTorch - -This repository includes software from https://github.com/facebookresearch/fairseq -licensed under the BSD License. - - diff --git a/PyTorch/NLP/Transformer/PATENTS b/PyTorch/NLP/Transformer/PATENTS deleted file mode 100644 index 18b09892..00000000 --- a/PyTorch/NLP/Transformer/PATENTS +++ /dev/null @@ -1,33 +0,0 @@ -Additional Grant of Patent Rights Version 2 - -"Software" means the fairseq software distributed by Facebook, Inc. - -Facebook, Inc. ("Facebook") hereby grants to each recipient of the Software -("you") a perpetual, worldwide, royalty-free, non-exclusive, irrevocable -(subject to the termination provision below) license under any Necessary -Claims, to make, have made, use, sell, offer to sell, import, and otherwise -transfer the Software. For avoidance of doubt, no license is granted under -Facebook’s rights in any patent claims that are infringed by (i) modifications -to the Software made by you or any third party or (ii) the Software in -combination with any software or other technology. - -The license granted hereunder will terminate, automatically and without notice, -if you (or any of your subsidiaries, corporate affiliates or agents) initiate -directly or indirectly, or take a direct financial interest in, any Patent -Assertion: (i) against Facebook or any of its subsidiaries or corporate -affiliates, (ii) against any party if such Patent Assertion arises in whole or -in part from any software, technology, product or service of Facebook or any of -its subsidiaries or corporate affiliates, or (iii) against any party relating -to the Software. Notwithstanding the foregoing, if Facebook or any of its -subsidiaries or corporate affiliates files a lawsuit alleging patent -infringement against you in the first instance, and you respond by filing a -patent infringement counterclaim in that lawsuit against that party that is -unrelated to the Software, the license granted hereunder will not terminate -under section (i) of this paragraph due to such counterclaim. - -A "Necessary Claim" is a claim of a patent owned by Facebook that is -necessarily infringed by the Software standing alone. - -A "Patent Assertion" is any lawsuit or other action alleging direct, indirect, -or contributory infringement or inducement to infringe any patent, including a -cross-claim or counterclaim. diff --git a/PyTorch/NLP/Transformer/README.md.old b/PyTorch/NLP/Transformer/README.md.old deleted file mode 100644 index 4848b0c6..00000000 --- a/PyTorch/NLP/Transformer/README.md.old +++ /dev/null @@ -1,563 +0,0 @@ -# Transformer For PyTorch - -This repository provides a script and recipe to train the Transformer model to achieve state of the art accuracy, and is tested and maintained by NVIDIA. - -## Table Of Contents -* [Model overview](#model-overview) - * [Model architecture](#model-architecture) - * [Default configuration](#default-configuration) - * [Feature support matrix](#feature-support-matrix) - * [Features](#features) - * [Mixed precision training](#mixed-precision-training) - * [Enabling mixed precision](#enabling-mixed-precision) - * [Enabling TF32](#enabling-tf32) - * [Glossary](#glossary) -* [Setup](#setup) - * [Requirements](#requirements) -* [Quick Start Guide](#quick-start-guide) -* [Advanced](#advanced) - * [Scripts and sample code](#scripts-and-sample-code) - * [Parameters](#parameters) - * [Command-line options](#command-line-options) - * [Getting the data](#getting-the-data) - * [Dataset guidelines](#dataset-guidelines) - * [Multi-dataset](#multi-dataset) - * [Training process](#training-process) - * [Inference process](#inference-process) -* [Performance](#performance) - * [Benchmarking](#benchmarking) - * [Training performance benchmark](#training-performance-benchmark) - * [Inference performance benchmark](#inference-performance-benchmark) - * [Results](#results) - * [Training accuracy results](#training-accuracy-results) - * [Training accuracy: NVIDIA DGX A100 (8x A100 40GB)](#training-accuracy-nvidia-dgx-a100-8x-a100-40gb) - * [Training accuracy: NVIDIA DGX-1 (8x V100 16GB)](#training-accuracy-nvidia-dgx-1-8x-v100-16gb) - * [Training stability test](#training-stability-test) - * [Training performance results](#training-performance-results) - * [Training performance: NVIDIA DGX A100 (8x A100 40GB)](#training-performance-nvidia-dgx-a100-8x-a100-40gb) - * [Training performance: NVIDIA DGX-1 (8x V100 16GB)](#training-performance-nvidia-dgx-1-8x-v100-16gb) - * [Training performance: NVIDIA DGX-2 (16x V100 32GB)](#training-performance-nvidia-dgx-2-16x-v100-32gb) - * [Inference performance results](#inference-performance-results) - * [Inference performance: NVIDIA DGX A100 (1x A100 40GB)](#inference-performance-nvidia-dgx-a100-1x-a100-40gb) - * [Inference performance: NVIDIA DGX-1 (1x V100 16GB)](#inference-performance-nvidia-dgx-1-1x-v100-16gb) -* [Release notes](#release-notes) - * [Changelog](#changelog) - * [Known issues](#known-issues) - - -## Model overview - -The Transformer is a Neural Machine Translation (NMT) model which uses attention mechanism to boost training speed and overall accuracy. The Transformer model was introduced in [Attention Is All You Need](https://arxiv.org/abs/1706.03762) and improved in [Scaling Neural Machine Translation](https://arxiv.org/abs/1806.00187). -This implementation is based on the optimized implementation in [Facebook's Fairseq NLP toolkit](https://github.com/pytorch/fairseq), built on top of PyTorch. - -This model is trained with mixed precision using Tensor Cores on NVIDIA Volta, Turing and Ampere GPU architectures. Therefore, researchers can get results 6.5x faster than training without Tensor Cores, while experiencing the benefits of mixed precision training. This model is tested against each NGC monthly container release to ensure consistent accuracy and performance over time. - -### Model architecture - -The Transformer model uses standard NMT encoder-decoder architecture. This model unlike other NMT models, uses no recurrent connections and operates on fixed size context window. -The encoder stack is made up of N identical layers. Each layer is composed of the following sublayers: - 1. Self-attention layer - 2. Feedforward network (which is 2 fully-connected layers) -Like the encoder stack, the decoder stack is made up of N identical layers. Each layer is composed of the sublayers: - 1. Self-attention layer - 2. Multi-headed attention layer combining encoder outputs with results from - the previous self-attention layer. - 3. Feedforward network (2 fully-connected layers) - -The encoder uses self-attention to compute a representation of the input sequence. The decoder generates the output sequence one token at a time, taking the encoder output and previous decoder-outputted tokens as inputs. -The model also applies embeddings on the input and output tokens, and adds a constant positional encoding. The positional encoding adds information about the position of each token. - -

- -
- Figure 1. The architecture of a Transformer model. -

- -The complete description of the Transformer architecture can be found in [Attention Is All You Need](https://arxiv.org/abs/1706.03762) paper. -### Default configuration - -The Transformer uses Byte Pair Encoding tokenization scheme using [Moses decoder](https://github.com/moses-smt/mosesdecoder). This is a lossy compression method (we drop information about white spaces). Tokenization is applied over whole [WMT14](http://statmt.org/wmt14/translation-task.html#Download) en-de dataset including test set. Default vocabulary size is 33708, excluding all special tokens. Encoder and decoder are using shared embeddings. -We use 6 blocks in each encoder and decoder stacks. Self attention layer computes it's outputs according to the following formula $`Attention(Q,K,V) = softmax(\frac{QK^T}{\sqrt{d_k}})V`$. At each attention step, the model computes 16 different attention representations (which we will call attention heads) and concatenates them. -We trained the Transformer model using the Adam optimizer with betas `(0.9, 0.997)`, epsilon `1e-9` and learning rate `6e-4`. We used the inverse square root training schedule preceded with linear warmup of 4000 steps. -The implementation allows to perform training in mixed precision. We use dynamic loss scaling and custom mixed precision optimizer. Distributed multi-GPU and multi-Node is implemented with `torch.distirbuted` module with NCCL backend. -For inference, we use beam search with default beam size of 5. Model performance is evaluated with BLEU4 metrics. For clarity, we report internal (legacy) BLEU implementation as well as external [SacreBleu](https://github.com/mjpost/sacreBLEU) score. - -### Feature support matrix - -The following features are supported by this model.
- -| Feature | Yes column -|--------------------------|-------------------------- -| Multi-GPU training with [Distributed Communication Package](https://pytorch.org/docs/stable/distributed.html) | Yes -| Nvidia APEX | Yes -| AMP | Yes -| TorchScript | Yes - -#### Features - -* Multi-GPU training with [Distributed Communication Package](https://pytorch.org/docs/stable/distributed.html): Our model uses torch.distributed package to implement efficient multi-GPU training with NCCL. -To enable multi-GPU training with torch.distributed, you have to initialize your model identically in every process spawned by torch.distributed.launch. Distributed strategy is implemented with APEX's DistributedDataParallel. -For details, see example sources in this repo or see the [pytorch tutorial](https://pytorch.org/docs/stable/distributed.html) - -* Nvidia APEX: The purpose of the APEX is to provide easy and intuitive framework for distributed training and mixed precision training. For details, see official [APEX repository](https://github.com/NVIDIA/apex). - -* AMP: This implementation uses Apex's AMP to perform mixed precision training. - -* TorchScript: Transformer can be converted to TorchScript format offering ease of deployment on platforms without Python dependencies. For more information see official [TorchScript](https://pytorch.org/docs/stable/jit.html) documentation. - - -### Mixed precision training -Mixed precision is the combined use of different numerical precisions in a computational method. [Mixed precision](https://arxiv.org/abs/1710.03740) training offers significant computational speedup by performing operations in half-precision format, while storing minimal information in single-precision to retain as much information as possible in critical parts of the network. Since the introduction of [Tensor Cores](https://developer.nvidia.com/tensor-cores) in the Volta and Turing architecture, significant training speedups are experienced by switching to mixed precision -- up to 3x overall speedup on the most arithmetically intense model architectures. Using mixed precision training requires two steps: -1. Porting the model to use the FP16 data type where appropriate. -2. Adding loss scaling to preserve small gradient values. - -The ability to train deep learning networks with lower precision was introduced in the Pascal architecture and first supported in [CUDA 8](https://devblogs.nvidia.com/parallelforall/tag/fp16/) in the NVIDIA Deep Learning SDK. - -For information about: -- How to train using mixed precision, see the [Mixed Precision Training](https://arxiv.org/abs/1710.03740) paper and [Training With Mixed Precision](https://docs.nvidia.com/deeplearning/sdk/mixed-precision-training/index.html) documentation. -- Techniques used for mixed precision training, see the [Mixed-Precision Training of Deep Neural Networks](https://devblogs.nvidia.com/mixed-precision-training-deep-neural-networks/) blog. -- APEX tools for mixed precision training, see the [NVIDIA Apex: Tools for Easy Mixed-Precision Training in PyTorch](https://devblogs.nvidia.com/apex-pytorch-easy-mixed-precision-training/). - -#### Enabling mixed precision - -Mixed precision is enabled using the `--amp` option in the `train.py` script. The default is optimization level `O2` but can be overriden with `--amp-level $LVL` option (for details see [amp documentation](https://nvidia.github.io/apex/amp.html)). Forward and backward pass are computed with FP16 precision with exclusion of a loss function which is computed in FP32 precision. Default optimization level keeps a copy of a model in higher precision in order to perform accurate weight update. After the update FP32 weights are again copied to FP16 model. We use dynamic loss scaling with initial scale of 2^7 increasing it by a factor of 2 every 2000 successful iterations. Overflow is being checked after reducing gradients from all of the workers. If we encounter infs or nans the whole batch is dropped. - -#### Enabling TF32 -TensorFloat-32 (TF32) is the new math mode in [NVIDIA A100](https://www.nvidia.com/en-us/data-center/a100/) GPUs for handling the matrix math also called tensor operations. TF32 running on Tensor Cores in A100 GPUs can provide up to 10x speedups compared to single-precision floating-point math (FP32) on Volta GPUs. - -TF32 Tensor Cores can speed up networks using FP32, typically with no loss of accuracy. It is more robust than FP16 for models which require high dynamic range for weights or activations. - -For more information, refer to the [TensorFloat-32 in the A100 GPU Accelerates AI Training, HPC up to 20x](https://blogs.nvidia.com/blog/2020/05/14/tensorfloat-32-precision-format/) blog post. - -TF32 is supported in the NVIDIA Ampere GPU architecture and is enabled by default. - - -### Glossary - -Attention layer - Layer that computes which elements of input sequence or it's hidden representation contribute the most to the currently considered output element. -Beam search - A heuristic search algorithm which at each step of predictions keeps N most possible outputs as a base to perform further prediction. -BPE - Binary Pair Encoding, compression algorithm that find most common pair of symbols in a data and replaces them with new symbol absent in the data. -EOS - End of a sentence. -Self attention layer - Attention layer that computes hidden representation of input using the same tensor as query, key and value. -Token - A string that is representable within the model. We also refer to the token's position in the dictionary as a token. There are special non-string tokens: alphabet tokens (all characters in a dataset), EOS token, PAD token. -Tokenizer - Object that converts raw strings to sequences of tokens. -Vocabulary embedding - Layer that projects one-hot token representations to a high dimensional space which preserves some information about correlations between tokens. - -## Setup - -The following section lists the requirements in order to start training the Transformer model. - -### Requirements - -This repository contains Dockerfile which extends the PyTorch NGC container and encapsulates some dependencies. Aside from these dependencies, ensure you have the following components: - -- [NVIDIA Docker](https://github.com/NVIDIA/nvidia-docker) -- [PyTorch 20.03-py3+ NGC container](https://ngc.nvidia.com/registry/nvidia-pytorch) -- GPU-based architecture: - - [NVIDIA Volta](https://www.nvidia.com/en-us/data-center/volta-gpu-architecture/) - - [NVIDIA Turing](https://www.nvidia.com/en-us/geforce/turing/) - - [NVIDIA Ampere architecture](https://www.nvidia.com/en-us/data-center/nvidia-ampere-gpu-architecture/) - -For more information about how to get started with NGC containers, see the following sections from the NVIDIA GPU Cloud Documentation and the Deep Learning Documentation: -- [Getting Started Using NVIDIA GPU Cloud](https://docs.nvidia.com/ngc/ngc-getting-started-guide/index.html) -- [Accessing And Pulling From The NGC Container Registry](https://docs.nvidia.com/deeplearning/dgx/user-guide/index.html#accessing_registry) -- Running [PyTorch NGC container](https://ngc.nvidia.com/catalog/containers/nvidia:pytorch) - -For those unable to use the PyTorch NGC container, to set up the required environment or create your own container, see the versioned [NVIDIA Container Support Matrix](https://docs.nvidia.com/deeplearning/frameworks/support-matrix/index.html). - -## Quick Start Guide -To train your model using mixed or TF32 precision with Tensor Cores or using FP32, perform the following steps using the default parameters of the Transformer model on the [WMT14 English-German](http://statmt.org/wmt14/translation-task.html#Download) dataset. For the specifics concerning training and inference, see the [Advanced](#advanced) section. - -1. Clone the repository -``` -git clone https://github.com/NVIDIA/DeepLearningExamples.git -cd DeepLearningExamples/PyTorch/Translation/Transformer -``` - -2. Build and launch the Transformer PyTorch NGC container -```bash -docker build . -t your.repository:transformer -nvidia-docker run -it --rm --ipc=host your.repository:transformer bash -``` -If you already have preprocessed data, use: -```bash -nvidia-docker run -it --rm --ipc=host -v :/data/wmt14_en_de_joined_dict your.repository:transformer bash -``` -If you already have data downloaded, but it has not yet been preprocessed, use: -```bash -nvidia-docker run -it --rm --ipc=host -v :/workspace/translation/examples/translation/orig your.repository:transformer bash -``` -3. Download and preprocess dataset: Download and preprocess the WMT14 English-German dataset. - -```bash -scripts/run_preprocessing.sh -``` -After running this command, data will be downloaded to `/workspace/translation/examples/translation/orig` directory and this data will be processed and put into `/data/wmt14_en_de_joined_dict` directory. - -4. Start training -```bash -python -m torch.distributed.launch --nproc_per_node 8 /workspace/translation/train.py /data/wmt14_en_de_joined_dict \ - --arch transformer_wmt_en_de_big_t2t \ - --share-all-embeddings \ - --optimizer adam \ - --adam-betas '(0.9, 0.997)' \ - --adam-eps "1e-9" \ - --clip-norm 0.0 \ - --lr-scheduler inverse_sqrt \ - --warmup-init-lr 0.0 \ - --warmup-updates 4000 \ - --lr 0.0006 \ - --min-lr 0.0 \ - --dropout 0.1 \ - --weight-decay 0.0 \ - --criterion label_smoothed_cross_entropy \ - --label-smoothing 0.1 \ - --max-tokens 5120 \ - --seed 1 \ - --fuse-layer-norm \ - --amp \ - --amp-level O2 \ - --save-dir /workspace/checkpoints \ - --distributed-init-method env:// -``` - -The script saves checkpoints every epoch to the directory specified in the `--save-dir` option. In addition, the best performing checkpoint (in terms of loss) and the latest checkpoints are saved separately. -**WARNING**: If you don't have access to sufficient disk space, use the `--save-interval $N` option. The checkpoints are ~3.4GB large. For example, it takes the Transformer model 30 epochs for the validation loss to plateau. The default option is to save last checkpoint, the best checkpoint and a checkpoint for every epoch, which means (30+1+1)*3.4GB = 108.8GB of a disk space used. Specifying `--save-interval 10` reduces this to (30/10+1+1)*3.4GB = 17GB. - -5. Start interactive inference -```bash -python inference.py \ - --buffer-size 5000 \ - --path /path/to/your/checkpoint.pt \ - --max-tokens 10240 \ - --fuse-dropout-add \ - --remove-bpe \ - --bpe-codes /path/to/bpe_code_file \ - --fp16 -``` -where, -* `--path` option is the location of the checkpoint file. -* `--bpe-codes` option is the location of the `code` file. If the default training command mentioned above is used, this file can be found in the preprocessed data ( i.e., `/data/wmt14_en_de_joined_dict` ) directory. - -## Advanced -The following sections provide greater details of the dataset, running training and inference, and the training results. - -### Scripts and sample code - -The `preprocess.py` script performs binarization of the dataset obtained and tokenized by the `examples/translation/prepare-wmt14en2de.sh` script. The `train.py` script contains training loop as well as statistics gathering code. Steps performed in single training step can be found in `fairseq/ddp_trainer.py`. Model definition is placed in the file `fairseq/models/transformer.py`. Model specific modules including multiheaded attention and sinusoidal positional embedding are inside the `fairseq/modules/` directory. Finally, the data wrappers are placed inside the `fairseq/data/` directory. - -### Parameters - -In this section we give a user friendly description of the most common options used in the `train.py` script. -### Command-line options -`--arch` - select the specific configuration for the model. You can select between various predefined hyper parameters values like number of encoder/decoder blocks, dropout value or size of hidden state representation.
-`--share-all-embeddings` - use the same set of weights for encoder and decoder words embedding.
-`--optimizer` - choose optimization algorithm.
-`--clip-norm` - set a value that gradients will be clipped to.
-`--lr-scheduler` - choose learning rate change strategy.
-`--warmup-init-lr` - start linear warmup with a learning rate at this value.
-`--warmup-updates` - set number of optimization steps after which linear warmup will end.
-`--lr` - set learning rate.
-`--min-lr` - prevent learning rate to fall below this value using arbitrary learning rate schedule.
-`--dropout` - set dropout value.
-`--weight-decay` - set weight decay value.
-`--criterion` - select loss function.
-`--label-smoothing` - distribute value of one-hot labels between all entries of a dictionary. Value set by this option will be a value subtracted from one-hot label.
-`--max-tokens` - set batch size in terms of tokens.
-`--max-sentences` - set batch size in terms of sentences. Note that then the actual batchsize will vary a lot more than when using `--max-tokens` option.
-`--seed` - set random seed for NumPy and PyTorch RNGs.
-`--max-epochs` - set the maximum number of epochs.
-`--online-eval` - perform inference on test set and then compute BLEU score after every epoch.
-`--target-bleu` - works like `--online-eval` and sets a BLEU score threshold which after being attained will cause training to stop.
-`--amp` - use mixed precision.
-`--save-dir` - set directory for saving checkpoints.
-`--distributed-init-method` - method for initializing torch.distributed package. You can either provide addresses with the `tcp` method or use the envionment variables initialization with `env` method
-`--update-freq` - use gradient accumulation. Set number of training steps across which gradient will be accumulated.
- -To see the full list of available options and their descriptions, use the `-h` or `--help` command line option, for example: -``` -python train.py --help -``` - -The following (partial) output is printed when running the sample: -``` -usage: train.py [-h] [--no-progress-bar] [--log-interval N] - [--log-format {json,none,simple,tqdm}] [--seed N] [--fp16] - [--task TASK] [--skip-invalid-size-inputs-valid-test] [--max-tokens N] - [--max-sentences N] [--sentencepiece] [--train-subset SPLIT] - [--valid-subset SPLIT] [--max-sentences-valid N] - [--gen-subset SPLIT] [--num-shards N] [--shard-id ID] - [--distributed-world-size N] - [--distributed-rank DISTRIBUTED_RANK] - [--local_rank LOCAL_RANK] - [--distributed-backend DISTRIBUTED_BACKEND] - [--distributed-init-method DISTRIBUTED_INIT_METHOD] - [--distributed-port DISTRIBUTED_PORT] [--device-id DEVICE_ID] - --arch ARCH [--criterion CRIT] [--max-epoch N] - [--max-update N] [--target-bleu TARGET] [--clip-norm NORM] - [--sentence-avg] [--update-freq N] [--optimizer OPT] - [--lr LR_1,LR_2,...,LR_N] [--momentum M] [--weight-decay WD] - [--lr-scheduler LR_SCHEDULER] [--lr-shrink LS] [--min-lr LR] - [--min-loss-scale D] [--enable-parallel-backward-allred-opt] - [--parallel-backward-allred-opt-threshold N] - [--enable-parallel-backward-allred-opt-correctness-check] - [--save-dir DIR] [--restore-file RESTORE_FILE] - [--save-interval N] [--save-interval-updates N] - [--keep-interval-updates N] [--no-save] - [--no-epoch-checkpoints] [--validate-interval N] [--path FILE] - [--remove-bpe [REMOVE_BPE]] [--cpu] [--quiet] [--beam N] - [--nbest N] [--max-len-a N] [--max-len-b N] [--min-len N] - [--no-early-stop] [--unnormalized] [--no-beamable-mm] - [--lenpen LENPEN] [--unkpen UNKPEN] - [--replace-unk [REPLACE_UNK]] [--score-reference] - [--prefix-size PS] [--sampling] [--sampling-topk PS] - [--sampling-temperature N] [--print-alignment] - [--model-overrides DICT] [--online-eval] - [--bpe-codes CODES] [--fuse-dropout-add] [--fuse-relu-dropout] -``` - -### Getting the data - -The Transformer model was trained on the [WMT14 English-German](http://statmt.org/wmt14/translation-task.html#Download) dataset. Concatenation of the *commoncrawl*, *europarl* and *news-commentary* is used as train and validation dataset and *newstest2014* is used as test dataset.
-This repository contains the `run_preprocessing.sh` script which will automatically downloads and preprocesses the training and test datasets. By default, data will be stored in the `/data/wmt14_en_de_joined_dict` directory.
-Our download script utilizes [Moses decoder](https://github.com/moses-smt/mosesdecoder) to perform tokenization of the dataset and [subword-nmt](https://github.com/rsennrich/subword-nmt) to segment text into subword units (BPE). By default, the script builds a shared vocabulary of 33708 tokens, which is consistent with [Scaling Neural Machine Translation](https://arxiv.org/abs/1806.00187). - -#### Dataset guidelines - -The Transformer model works with a fixed sized vocabulary. Prior to the training, we need to learn a data representation that allows us to store the entire dataset as a sequence of tokens. To achieve this we use Binary Pair Encoding. This algorithm builds a vocabulary by iterating over a dataset, looking for the most frequent pair of symbols and replacing them with a new symbol, yet absent in the dataset. After identifying the desired number of encodings (new symbols can also be merged together) it outputs a code file that is used as an input for the `Dictionary` class. -This approach does not minimize the length of the encoded dataset, however this is allowed using [SentencePiece](https://github.com/google/sentencepiece/) to tokenize the dataset with the unigram model. This approach tries to find encoding that is close to the theoretical entropy limit. -Data is then sorted by length (in terms of tokens) and examples with similar length are batched together, padded if necessary. - -#### Multi-dataset - -The model has been tested oni the [wmt14 en-fr](http://www.statmt.org/wmt14/translation-task.html) dataset. Achieving state of the art accuracy of 41.4 BLEU. - -### Training process - -The default training configuration can be launched by running the `train.py` training script. By default, the script saves one checkpoint every epoch in addition to the latest and the best ones. The best checkpoint is considered the one with the lowest value of loss, not the one with the highest BLEU score. To override this behavior use the `--save-interval $N` option to save epoch checkpoints every N epoch or `--no-epoch-checkpoints` to disable them entirely (with this option the latest and the best checkpoints still will be saved). Specify save the directory with `--save-dir` option.
-In order to run multi-GPU training, launch the training script with `python -m torch.distributed.launch --nproc_per_node $N` prepended, where N is the number of GPUs. -We have tested reliance on up to 16 GPUs on a single node.
-After each training epoch, the script runs a loss validation on the validation split of the dataset and outputs the validation loss. By default the evaluation after each epoch is disabled. To enable it, use the `--online-eval` option or to use the BLEU score value as the training stopping condition use the `--target-bleu $TGT` option. The BLEU scores computed are case insensitive. The BLEU is computed by the internal fairseq algorithm which implementation can be found in the `fairseq/bleu.py` script.
-By default, the `train.py` script will launch FP32 training without Tensor Cores. To use mixed precision with Tensor Cores use the `--fp16` option.
- -To reach the BLEU score reported in [Scaling Neural Machine Translation](https://arxiv.org/abs/1806.00187) research paper, we used mixed precision training with a batch size of 5120 per GPU and learning rate of 6e-4 on a DGX-1V system with 8 Tesla V100s 16G. If you use a different setup, we recommend you scale your hyperparameters by applying the following rules: -1. To use FP32, reduce the batch size to 2560 and set the `--update-freq 2` option. -2. To train on a fewer GPUs, multiply `--update-freq` by the reciprocal of the scaling factor. - -For example, when training in FP32 mode on 4 GPUs, use the `--update-freq=4` option. - -### Inference process - -Inference on a raw input can be performed by piping file to be translated into the `inference.py` script. It requires a pre-trained model checkpoint, BPE codes file and dictionary file (both are produced by the `run_preprocessing.sh` script and can be found in the dataset directory).
-In order to run interactive inference, run command: -``` -python inference.py --path /path/to/your/checkpoint.pt --fuse-dropout-add --remove-bpe --bpe-codes /path/to/code/file -``` -The `--buffer-size` option allows the batching of input sentences up to `--max_token` length. - -To test model checkpoint accuracy on wmt14 test set run following command: - -```bash -sacrebleu -t wmt14/full -l en-de --echo src | python inference.py --buffer-size 5000 --path /path/to/your/checkpoint.pt --max-tokens 10240 --fuse-dropout-add --remove-bpe --bpe-codes /data/code --fp16 | sacrebleu -t wmt14/full -l en-de -lc -``` - -## Performance - -The performance measurements in this document were conducted at the time of publication and may not reflect the performance achieved from NVIDIA’s latest software release. For the most up-to-date performance measurements, go to [NVIDIA Data Center Deep Learning Product Performance](https://developer.nvidia.com/deep-learning-performance-training-inference). - -### Benchmarking - -The following section shows how to run benchmarks measuring the model performance in training and inference modes. - -#### Training performance benchmark - -To benchmark the training performance on a specific batch size, run `train.py` training script. Performance in tokens/s will be printed to standard output every N iterations, specified by the `--log-interval` option. Additionally performance and loss values will be logged by [dllogger](https://github.com/NVIDIA/dllogger) to the file specified in `--stat-file` option. Every line in the output file will be a valid JSON file prepended with `DLLL` prefix. - -#### Inference performance benchmark - -To benchmark the inference performance on a specific batch size, run following command to start the benchmark -```bash -for i in {1..10}; do sacrebleu -t wmt14/full -l en-de --echo src; done | python inference.py --buffer-size 5000 --path /path/to/your/checkpoint.pt --max-tokens 10240 --fuse-dropout-add --remove-bpe --bpe-codes /data/code --fp16 > /dev/null -``` -Results will be printed to stderr. - -### Results - -The following sections provide details on how we achieved our performance and accuracy in training and inference. - -#### Training accuracy results - -Following the spirit of the paper [A Call for Clarity in Reporting BLEU Scores](https://arxiv.org/pdf/1804.08771.pdf) we decided to change evaluation metric implemented in fairseq to [SacreBleu](https://github.com/mjpost/sacreBLEU) score. We have calculated that the new metric has almost linear relationship with the old one. We run linear regression on nearly 2000 checkpoints to discover that the SacreBleu score almost perfectly follows the formula: newScore = 0.978 * oldScore - 0.05. -

- -
- Figure 2. Linear relationship between old and new BLEU metric. -

-To take into account the varibaility of the results we computed basic statistics that help us verify whether a model trains correctly. Evaluating nearly 2000 checkpoints from 20 runs, the best score we achieved is 28.09 BLEU (which corresponds to 28.77 old score). Variance of the score of the best performing model between those 20 runs is 0.011. Knowing that max statistic is skewed toward higher values we have also run studies which calculate threshold beyond which validation loss is no longer correlated with BLEU score. -Of course our hope is that dev's set distribution is similar to test's set distribution and when validation loss drops, BLEU score rises. But due to the finiteness of the validation and test sets we expect that there is such a loss value that makes performance on both sets decoupled from each other. To find this point we used Pearson correlation coefficient as a metric. The results indicate that optimizing beyond 4.02 validation loss value is no longer beneficial for the BLEU score. Further optimization does not cause overfitting but results become stochastic. -Mean BLEU score after reaching 4.02 validation loss is 27.38. We observe variance of 0.08, which translate to nearly 0.3 BLEU average difference between mean score and obtained score. -

- -
- Figure 3. Validation loss vs BLEU score. Plots are trimmed to certain validation loss threshold. -

- -##### Training accuracy: NVIDIA DGX A100 (8x A100 40GB) -Our results were obtained by running the `run_DGXA100_AMP_8GPU.sh` and `run_DGXA100_TF32_8GPU.sh` training scripts in the pytorch-20.06-py3 NGC container on NVIDIA DGX A100 (8x A100 40GB) GPUs. We report average accuracy over 6 runs. We consider a model trained when it reaches minimal validation loss. Time to train contains only training time without validation. Depending on a configuration and frequency of validation it can take up to additional minute per epoch. - -| GPUs | Batch size / GPU | Accuracy - TF32 | Accuracy - mixed precision | Time to train - TF32 | Time to train - mixed precision | Time to train speedup (TF32 to mixed precision) -|---------|---------------------|------------------|-----------------------------|-------------------------|----------------------------------|------------------------------------ -| 8 | 10240 | 27.92 | 27.76 | 2.87 hours | 2.79 hours | x1.03 - -##### Training accuracy: NVIDIA DGX-1 (8x V100 16GB) - -Our results were obtained by running the `run_DGX1_AMP_8GPU.sh` and `run_DGX1_FP32_8GPU.sh` training scripts in the pytorch-20.06-py3 NGC container on NVIDIA DGX-1 (8x V100 16GB) GPUs. We report average accuracy over 6 runs. We consider a model trained when it reaches minimal validation loss. Time to train contains only training time without validation. Depending on a configuration and frequency of validation it can take up to additional minute per epoch. Using mixed precision we could fit a larger batch size in the memory, further speeding up the training. - -| GPUs | Batch size / GPU | Accuracy - FP32 | Accuracy - mixed precision | Time to train - FP32 | Time to train - mixed precision | Time to train speedup (FP32 to mixed precision) -|---------|---------------------|------------------|-----------------------------|-------------------------|----------------------------------|------------------------------------ -| 8 | 5120/2560 | 27.66 | 27.82 | 12 hours | 4.6 hours | x2.64 - -#### Training performance results - -##### Training performance: NVIDIA DGX A100 (8x A100 40GB) - -Our results were obtained by running the `run_DGXA100_AMP_8GPU.sh` and `run_DGXA100_TF32_8GPU.sh` training scripts in the pytorch-20.06-py3 NGC container on NVIDIA DGX A100 (8x A100 40GB) GPUs. Performance numbers (in tokens per second) were averaged over an entire training epoch. - -| GPUs | Batch size / GPU | Throughput - TF32 | Throughput - mixed precision | Throughput speedup (TF32 - mixed precision) | Weak scaling - TF32 | Weak scaling - mixed precision -|--------|--------------------|----------------------|---------------------------------|-----------------------------------------------|------------------------|----- -| 8 | 10240 | 316913 | 582721 | x1.84 | 6.93 | 7.05 -| 4 | 10240 | 161980 | 298741 | x1.84 | 3.54 | 3.62 -| 1 | 10240 | 45755 | 82618 | x1.81 | 1 | 1 - - -To achieve these same results, follow the steps in the [Quick Start Guide](#quick-start-guide). - -##### Training stability test - -The following plot shows average validation loss curves for different configs. We can see that training with AMP O2 converges slightly slower that FP32 and TF32 training. In order to mitigate this, you can use option `--amp-level O1` at the cost of 20% performance drop compared to the default AMP setting. - -

- -
- Figure 4. Validation loss curves -

- -##### Training performance: NVIDIA DGX-1 (8x V100 16GB) - -Our results were obtained by running the `run_DGX1_AMP_8GPU.sh` and `run_DGX1_FP32_8GPU.sh` training scripts in the pytorch-20.06-py3 NGC container on NVIDIA DGX-1 with (8x V100 16GB) GPUs. Performance numbers (in tokens per second) were averaged over an entire training epoch. Using mixed precision we could fit a larger batch size in the memory, further speeding up the training. - -| GPUs | Batch size / GPU | Throughput - FP32 | Throughput - mixed precision | Throughput speedup (FP32 - mixed precision) | Weak scaling - FP32 | Weak scaling - mixed precision -|--------|--------------------|----------------------|---------------------------------|-----------------------------------------------|------------------------|----- -| 8 | 5120/2560 | 58742 | 223245 | x3.80 | 6.91 | 6.67 -| 4 | 5120/2560 | 29674 | 115269 | x3.88 | 3.49 | 3.44 -| 1 | 5120/2560 | 8498 | 33468 | x3.94 | 1 | 1 - - -To achieve these same results, follow the steps in the [Quick Start Guide](#quick-start-guide). - -##### Training performance: NVIDIA DGX-2 (16x V100 32GB) - -Our results were obtained by running the `run_DGX1_AMP_8GPU.sh` and `run_DGX1_FP32_8GPU.sh` training scripts setting number of GPUs to 16 in the pytorch-20.06-py3 NGC container on NVIDIA DGX-2 with (16x V100 32GB) GPUs. Performance numbers (in tokens per second) were averaged over an entire training epoch. Using mixed precision we could fit a larger batch size in the memory, further speeding up the training. - -| GPUs | Batch size / GPU | Throughput - FP32 | Throughput - mixed precision | Throughput speedup (FP32 - mixed precision) | Weak scaling - FP32 | Weak scaling - mixed precision -|--------|--------------------|----------------------|---------------------------------|-----------------------------------------------|------------------------|----- -| 16 | 10240/5120 | 130867 | 510267 | x3.9 | 13.38 | 12.7 -| 8 | 10240/5120 | 68829 | 269464 | x3.91 | 7.04 | 6.71 -| 4 | 10240/5120 | 35168 | 141143 | x4.01 | 3.6 | 3.51 -| 1 | 10240/5120 | 9779 | 40163 | x4.11 | 1 | 1 - - -To achieve these same results, follow the steps in the [Quick Start Guide](#quick-start-guide). - -#### Inference performance results - -Our implementation of the Transformer has dynamic batching algorithm, which batches sentences together in such a way that there are no more than `N` tokens in each batch or no more than `M` sentences in each batch. In this benchmark we use the first option in order to get the most stable results. - -##### Inference performance: NVIDIA DGX A100 (1x A100 40GB) - -Our results were obtained by running the `inference.py` inferencing benchmarking script in the pytorch-20.06-py3 NGC container on NVIDIA DGX A100 (1x A100 40GB) GPU. - -FP16 - -| Batch size | Throughput Avg | Latency Avg | Latency 90% |Latency 95% |Latency 99% | -|------------|-----------------|-------------|-------------|------------|------------| -| 10240 | 9653 | 0.986s | 1.291s | 2.157s | 2.167s | -| 2560 | 5092 | 0.504s | 0.721s | 0.830s | 1.752s | -| 1024 | 2590 | 0.402s | 0.587s | 0.666s | 0.918s | -| 512 | 1357 | 0.380s | 0.561s | 0.633s | 0.788s | -| 256 | 721 | 0.347s | 0.513s | 0.576s | 0.698s | - -TF32 - -| Batch size | Throughput Avg | Latency Avg | Latency 90% |Latency 95% |Latency 99% | -|------------|----------------|-------------|-------------|------------|------------| -| 10240 | 7755 | 1.227s | 1.592s | 2.512s | 2.525s | -| 2560 | 4624 | 0.555s | 0.786s | 0.872s | 1.886s | -| 1024 | 2394 | 0.435s | 0.627s | 0.702s | 0.881s | -| 512 | 1275 | 0.405s | 0.586s | 0.663s | 0.821s | -| 256 | 677 | 0.370s | 0.546s | 0.613s | 0.733s | - -To achieve these same results, follow the steps in the [Quick Start Guide](#quick-start-guide). - -##### Inference performance: NVIDIA DGX-1 (1x V100 16GB) - -Our results were obtained by running the `inference.py` inferencing benchmarking script in the pytorch-20.06-py3 NGC container on NVIDIA DGX-1 with (1x V100 16GB) GPU. - -FP16 - -| Batch size | Throughput Avg | Latency Avg | Latency 90% |Latency 95% |Latency 99% | -|------------|----------------|-------------|-------------|------------|------------| -| 10240 | 7464 | 1.283s | 1.704s | 1.792s | 1.801s | -| 2560 | 3596 | 0.719s | 1.066s | 1.247s | 1.423s | -| 1024 | 1862 | 0.563s | 0.857s | 0.936s | 1.156s | -| 512 | 1003 | 0.518s | 0.782s | 0.873s | 1.103s | -| 256 | 520 | 0.484s | 0.723s | 0.813s | 0.992s | - -FP32 - -| Batch size | Throughput Avg | Latency Avg | Latency 90% | Latency 95% | Latency 99% | -|------------|----------------|-------------|-------------|-------------|-------------| -| 10240 | 3782 | 2.531s | 3.091s | 3.121s | 3.136s | -| 2560 | 2910 | 0.888s | 1.221s | 1.252s | 1.432s | -| 1024 | 1516 | 0.692s | 1.001s | 1.126s | 1.297s | -| 512 | 941 | 0.551s | 0.812s | 0.893s | 1.133s | -| 256 | 502 | 0.501s | 0.734s | 0.822s | 0.978s | - -To achieve these same results, follow the steps in the [Quick Start Guide](#quick-start-guide). - - -## Release notes - -### Changelog - -June 2020 -- add TorchScript support -- Ampere support - -March 2020 -- remove language modeling from the repository -- one inference script for large chunks of data as well as for interactive demo -- change custom distributed strategy to APEX's DDP -- replace custom fp16 training with AMP -- major refactoring of the codebase - -December 2019 -- Change evaluation metric - -August 2019 -- add basic AMP support - -July 2019 -- Replace custom fused operators with jit functions - -June 2019 -- New README - -March 2019 -- Add mid-training [SacreBLEU](https://pypi.org/project/sacrebleu/1.2.10/) evaluation. Better handling of OOMs. - -Initial commit, forked from [fairseq](https://github.com/pytorch/fairseq/commit/ac5fddfc691267285a84c81d39475411da5ed1c6) - -## Known issues - -- Using batch size greater than 16k causes indexing error in strided_batched_gemm module diff --git a/PyTorch/NLP/Transformer/average_valid_loss.png b/PyTorch/NLP/Transformer/average_valid_loss.png deleted file mode 100644 index 60b164f169e86d70098fc8ac7eec45c95602f1a6..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 18860 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 diff --git a/PyTorch/NLP/Transformer/bleu_relationship.png b/PyTorch/NLP/Transformer/bleu_relationship.png deleted file mode 100644 index 776ff385387b4efb13685f72d16d1cb349edb102..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 10460 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 B08#(| diff --git a/PyTorch/NLP/Transformer/decorrelation_threshold.png b/PyTorch/NLP/Transformer/decorrelation_threshold.png deleted file mode 100644 index 2129893a58e13e010e6645628a4b023868823932..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 177274 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%0D+sm3Zk!{jh2`}Ry2LbliJW-aD;^9fqUDW^% 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 z zF-8^#Q4jy6{Ph#abQuC%Ny(su&|Mi#FM!^^z2O$GLM{1%{X0%keELfjiTI$qTaCqzKEb)@T5%0Hk$f_+K=d)ka74 z&vOvg2Vp}n!H?2M3g6uJquK+ZI(BmLU`nwKuGjW;Ux8}s?a#mDP*4-i`6KpXsuq`4 z|Jwg&0YFHo#=$KFkrh*SB6w}@MW3LkD7u>5kMXUburLLQOcr)9az$UvlnJt#2iN_o z=z{KH0~d&jsl@!=?;VD?Qu&m3l`7dut?e@hN1+gZp4Xp60wpcHiEnL;XHE)Y9XMya zZKt>(h>v%d2DGkf8%|jd1)sih78*9cdN4qO)Hn2q}ngcdRg7AN>MDB<*MP^&0W&7#eZ0PBLV^IOY36J9#W2WO)wY@TL9+~->Hf!>^-ai({DX(6t~wX>=QXuJKZ$G< z!T{Jz2)HUX9f^t{1K~(ASa#S0(jE_62Ws=Fd>}R9dVNgzqmZ9%aZpKNQeG*}8fAKN ze0TRU#I)Id1llRC&TePBM(Ybam=l;-YFf~?+*^I{Z`5_$Efl}^hVOlDUjZYAg#A!n z5MFa9T#WA`v~k@(j6bh=*bl>oJdF}|YNSYVxf`&ULdtiGwGA4Nbf{AZtY3;lHF!F) zPh?RtczFWL{qb?Sg!43wA2&fIuTkNO{Ca@qpR)=g&5zLf3>m|XIp2Ym?j3(tlvxAE z>}1gP4Gd9$5tN$|-uliwD4Mn@?-qsEReOUWx0L zIevl04^~pM&A_+x*IRft_Jmh15ZD6W<4-oYqw78jdD1)r+^Ielr4O(A1XP10;m0@~ zzR9fwNYD`}=_$x$p$MR-gJ8mC_Z&GyP;*^jnQ$v8F#}Jz8f_Oie`LQ;6SByG+Fvmm992Qk5U(#QU;+8>v zbFzFXZzEPrfq*0hpHn+Eq|FFeUsfC4<|CLjDq$R#IRXY7E(N5>Oo<$bR8$MVPLpPB zDqOt1**tB3RlZ(hHY5Zxyz0Z94ohdK6G);U=9vy z8>CvMW9IzaVDAh_uQeS4pYz#g>z!96I5t#Gfoi&;U{vyDi)q*Vm75o!3=1R?eEc2g z>fq>`p2jV=(rZp2=`e>FZX7=vy!|Qe3v@9Dv=_}b`O(tbV?ix z#(2876jWPt2sPUMRWNFYZ4pSSQ+jM6z~|){?cdBp1%4S_?c%P1 zxjZYBUMcUh5+D5U7_8B1oQQ6V*oHqTmTJKNzcixqkLd(c7RDxa&|ti&gkLjqK|oA7N$G+s{ejHF*?f?ZQvEA24@f5vH9x7lQHC!bo!mdbBv zNO?Kg{hos>+6JiZ-ER2m(>u|~%C@m`V>?kKkm!bN8tNMvx{83(5oyB5{ui~?R=#2W z>!YdyY-I%WkCXtW`b(6129^}WvN=~Atg3;jx&26`T5iXDpHpJtlD&+Rr zgPs$WhNCbGFYd{HpLsdT3>wVmx$e46qcTr#)NIo83*;Ewm=7`!WtI){H|uK7>z|F%l9iF2wiSJ^YTE3mfDDH-%n~g%1Z`Y$ zL!Pve2|a>R7-OmYsaK-;q?zK#N;TZBE*-X(RZDvYS5p(BEf0m}hj*G#qWK~)(??2z zVHgQvl7{Z$h<*5rjkcmjXkVL;!UX>1CVK2)b(tkV!0ajEG-rVnnC(SS%;VjqCo&{N z#Qby3^(i0>4ZfIMNgm;!xQ#nG%~tmK3~rW9GP7szvPHs)8a!D*s2GGj!3+$z@Av0Z z8z+2wLybwA*eoMWfLzSSU^u6{P+(Tn2;Ak~4A8)$uV`QYG;F*#z$T%|&a_-M%IOC+ zzY;_?!B~m@RJNMk0rldtmx0J9zUAR!g3#-h9P`LaS{iyH;@jBTiv6^eZ_(|>95V0i zkOyR@p+`$83&(EqW>2#lD*eTinDaSHJt^?K=qG(g+HEpvm6)MaJ41#d4Snd(iCTS? zcaLeUke)x%(_3nai1fTw6J!-7v)D=%gdF>L_O410s5I9~YD>|HMh!Q}MNHS`yaVRP z!(-hP69EOWcG_6Jdl8yX(CFw!kxxrsQOnHo)q^i)vS)ses_WZg$nvEwaUdk~T%lSe zI7tdc#--tsLajlB^X9#yJ1x1rpo3h?NBfK@pEVAXwa97 ziAveh{F#HNo+lD)GTV`9q|MHe=BC=PNu%(XI4s>+0z8OU8+Gn8YuYnMe%8&BSPr-Z z87kxMisF*mIeT&;in7$$QGygnkcNxiVG9mSy+Mimqdmf)}- zrj<}(g3_ku+=o?pHNh5F-XBB3rtNjG0)=Ohz z$^AIr%wxvOE4;M@&CK3(ZkWk!?9#UgBp^fe>M(~OAySv~KfTDWE^GQ_n`!1$2T@fw zWyh&E{rWeU&=DNVSN;OBz01$K#GyseSh`t2bMtn9SArBzLI1olJSuJgW>W#X{Ye?b zdK4(#;K35IVZ^>{&+SJ#KEF#jXg2vb_CGJZuHm=ayNiUgh;yTQt9> zOs0VJr`Wt61d-4MA&ds&RUI;L6Ytv+Y)i8naBT^#_;VgbE;mjkP?XG*#(}a8ayTvr zL4u0wGedoH=FS((i~5j~JTTb4x$q+$>mc9hkOhnwW)HirZBo2Hz)S`tHS8ECL`Avb zab+d8p40U@m5}&(6RoI7t&zUXYO=6)pMpjI$Nxrs_hGvs7~uFG0_UWm%zU70E_Wv& zGLP`Aogi!P?_F-*cEVk(Rw~;m%OC8d2g5$GaYM`V%HW@1FdSEjg{)&avy?9~FH85gQlTxbm*l#VqRxc+^xpVR%4jk=pnrm1 z)Z&9{!W+{!hBxSI2KT|gALP7j=J5P+aY+VG5$LC8JmrzW0H5cL3z&)tL14B6jpcq@ zr=w@uq}Zs10-g>xy*o09;PDGFqxmUv1XxawvCB3M2CIwez0JBIAdXG9CQqCjx@I2z zjm-O*I?{CEg4c1C$u62)20u)CG;HI>>XT1D8o9=4N?>2PO+jx*ob}n^3@4f;o842Y z1uUhBVJ5I+8h7wjN}CtN(^jO_OX2`s=O;4NdCa_5APa4)Y_PGQ;U_c|{(7|kq_X9I zk}R54a<7)4J(k&RgQC3DcpXjz#uh$-ky^72o3QA9=U@2>tCQl&9=OJBRe>Nh1XSLj zzOjd#$Ea0l+-uqDYOe2dy}O-8f+HAWhhGj-@=#C{T56%hv0R>0vo!fkA;5sNu|}m) zW%c!7<#zniy_q+%Ra@t;BSbE97rTt_1l2z&&IgcV8lOwkK+c^)B+-#nKN>nTC3So5 z187tKrUdDUw2oy+z~u4lW^QJ02NaOzzWpEoql~~X0TZSmMg$Z0?k(qIN6HGWEtTN%$M+u_kWQJ9woVyNR+MgDuBxpuyo=hpr` znr*yGcaJ!TeZv!u66uOj^~_Bk?q>RcB&{dDV6=ON{e#j)lMdw-ceWtW*zekiAm)XivEJyRlE2@L>;uPfjfPN50m+7x|F- zZ)}zI4dPcj7+hL2y#Zc_G`D|w@+!-7Lr5a$)?=_frZ@uFa#hJn~u_Fv=*_ z%g-A0oyN~=OfKugp}>G0Htgy}P(L>Zxp z6xm00HNB{Ln#|#2JiD`TD^6H$mNSmJuUOB0W0@*f93_5GDJ2oP!?>2Qe}PL#ZT@js zZ#$e;%>Ksx>0$suR9hO$qG%DPexzsyENFNJWS$S|-}MF2 zU=pLzhca+b1+ZZF78QC4mO{@>1CvJRnd!Lvp8ukRWoHilfZ$W>rTv`S3+7^Q6UH#cf1kK317;;2wu}Y8VA=$(Vd!nu?6XpNU=;ID6UXP7)MmuqPC|SK7g=<;i!CN5cS{Z&crd+r!nOs?aXW}`>0ASEB21JJ zXW4c=>HIt1_BAppJEo@u*^Wv)H5q%5-VfINXsC3!1y6Pl=2_PfD0$8fOgLc@6KpmZ zq<+f%gjwo^pA^KuP91Tlf3FfR|+ ziqMk>WV)1CQSgevdxF$4xANp*GP;=>ebmwzXnmaZmSOZ= z-w%AbUNWQO^- z-?oD4Wv|sJaq_oPcJ4+yy&@;g>9PF_d$_B0j)kv#M#U-aZJZJ*Qv?uRh)0%muI3z3 z9Yz)mjM3Ruv&Y11cuco#blHNhdwwn8G%Hymrw3&L09KXe7bnb^CzJ}-Abr-U!x?Z_Ma8Imc>8|mTdQhEsKn=3Hz^rvPj zlcjJTA^NHp5O-+=2RtZF)y3f;_d!*by82b$q$Iqt-k2i7u&Y?+bZ%Iz2D9%)@d;^Q zmQV)Y5=_07hDnF-f|oS6!+!es%#>nJASdT=KIeMaR-F@I%!t>qajE>$QvZ0dG?;QS zUEA~xzMh4fEt%0e89XOcxfO%(cg34mB@U_aPr_D7QKKqwv=`r4N@dDX7I~wGS#eN} zJ!Ob6A4RJzzT;1^Zp|y@BK&sVWd&11>Dptb*`jsJtp2(Eq-9*R;UkSV!Py9dFZ!~! znCzw1hFCD^yw>n=z>>Gshr9}+I0q;3Y(*K4y1B6uc|FI0<#xV4*Qb{7;}>;%%N1;e zo)Djwn&%qHG0hQr*a{1I+6~nq`1({U9Vn(A`!cvH-=vwGK2#uaq7Y8J))A^A(*1b~ zuEIG-sX$Xg+0tn1dxKWJd)piluj;(Cj<7Arj_bog-6#p0!sMX3{-ygyZtwQ2ZDq-m z&|FCnDZATZ-gf{!-nB!|du30|rzU^}{gV6KgZSk~iu;&0x8M60J%Fys<_$8XFLl{M zmf4IUN@W<&jN;ZW1{BToTU6?>E_ZMBh_Fg{w1k>8vU@gkjf@D3*(AdhAbkf&O|Z39 z@;vXCEM`}@!uh36`u3?f)~^SXD@q>U#%`7N*A08}-aYn0D=cF54iTyYvk2Iq4m zcK4TZf4p>UTn&k56*DHH$H~{yNkQj>(t6u+I|aGm~m%ujB^n*RO#3`W%@Dmc-noF+|dSuUk% zg|g{TAlN(|Bk|2EiJD2lBmSf`8vyio(Gn$m-ao%>SEaPFcLCWMv6Q=?^$LOM`=^^LZuTf$%Ebw<~rM{i=X@zyw! zaX7H|G5(Y6%{w32pz(-4Y-N5p7+G#3jfqqHGdvuo-xD2`DD6w}K;L-7&DKLj3&7IX zoFD(~9#tJRc!h><#aTjv>11t9_!Rr23yDKNL4%4UTTgwkBfp!;?DeH!q37BMp~kb> zuNJF?Nrg-|Wg2hJb*O&Gr@GUg>RKyeBZZYi3cI&{~bwJykxHy7(QLs#1v|?_6+G!Rqpo_#o6aR%Nr!78y!WtwTVk8 z+Gcyf=Vxfyo5VUv5xN7xK39O8_-OQ!%TpV;iYHdQ=xFzLNIv5>3D5j1KwWCuvBB1b zVp4DVR7=K@Ksq_g$~GtbFA5I3r9Z654va@lJ(7Sq|C5+&wf}Vk8p6vqyYeZ`hX2YZ zuQBuWQ&*_|@@jci>%N`1XHHDBOUYmF^FVv1D*jPZ{+vs^x}-LEv=k~HjA?V6hX-U2-CtD$B_A;oiFFvY@6(Ma}oMA_+{NqB|O7rn+?F2);;H&Wk z%SX!FNV46s_wLtj#KMc(QdeXUO<*_L zvR0nH;s0Za3yjWWrxZ!~gkN4b8|UBP;TIdq_oUN~i`YSNA0=7%b%vs1KYC7an)sg& z&t5^0r?xn&O8Ih-yl{2Z1vBp_zo?d+dlzdw_WEw6nD0;wWn#1%j{mWU$lt*7*vE-Q z4-_8gd@E9aWj%d?L-rwE+O&rmw`p_RtQMp}gC*{FtJ=49Y)K z-T&kVADnLRm)zyi;L~T-GzoKT!TVum?u`vtL zh$LtFKEJ7-0WW28gnj=fDvFI@%u^-4NPO5?*RjCGa>LM$3LfEB` zAVb$R^g2oDIlX}ANMr>q;8_kU-%gG2xAza<59W{n^|0-k!e8b&kHWSS`&b_$_j{gr zB*l^H?FQztUfdpr$6V)^`G~pQb$n13=!;S0t?libtHQ-!^i-MXLRc@3bdJ46D8yht z(jq9w;F8MRm;W3&(LcRfD!5qkkr8&>&dX$?;|gV~&#PiH8fS!!%ss!WZFFPADl^$Y8|PVraaPG zosCog&bqGg-;BpP);w54`K>#G}b6MXTr(6 ze8K|D^)?!v*Z#tWMq?WL!YLmoqXe|f`4zt5-n9~(9dC)Ha{(R9^P1Z$|8}Uh1Ze)h z|M1Vr*y^THTKfsfzov8h;u-AMZn*U%cYPPQVpYvjESyiI$wia&XX_F05u_Y}?W{om z--drQ61FaS{9W&xfY|V}cxmsyal%l7<6~M&Bf0Ml43SKQ+DNupA81~#5nq~EUpA+C z(-o#<)T)2*XQ&fuwf?6m{(GT60geWcF+*t-6h3a1qrn=|fudWj>XxSV8{;S125SLI zPko{OQp>$%bn%jln0zkvnNV@8ivbCUQXzS)O+oq^?w0=0&ifh@AV*(T)%CpY-eNG| zPid?f-9%0&qAAl64a7IY0?l>oHtr}TvV~2ON<<#ivM5}uKLs5>#lG9$OG=6{7dcZ5 zt*#K9Cz^sI;W>EZu>yNhaJF9SqU5T5DZ!B`OLIA8TR!)4r%4F|;J~ca1^Mi&6Jf~5 zo+6n0$@<&z#`YBhXV$BQ(&?JUeQe#GUegzc)0M#z4CRy0Lh;xh(Ng98q{^psh8@3! zEv(r31`r6#t$3h%y<~MPz6#=MFMkPHPDc6gIw<N^&|y5PI@@z? zyqbSlx{Ikw^Zper)daK~O!*xBA5B*oly&=b>5}daX({PWY3W8%x{>bg77(OCy1PT^ zzCj+k1*E$h-phC9KjSBc!CzgwXU{pi+imwr8dVS_v((Co$_6He1Lfo3^$ts%==S-D zkXz4tR-$E+8s^LU7iY4S>~{zxe1m6B6CVYw+&sZu4V;`$?UZ!5luKNLXR45&mwf&F zVa`r5Hb1Z;VwWrW>@NntfHI_1IQ~&P^78H3UcR`mPigdrrRIqepRxNJSxsZ^g_F(I zN)x)9ICFEYye#?F0kIA}11#lOB$MNFVj4NR1rsyN&mR&d_iNy9Z!}E-I~O%Z|M~xG z)uk<4O%<8efjIYg&F0S>k*j>xr>Cr2;f&UB>5|U20)&f#Nxcu~^2B5-4)FZIEbLWVl1PIt00{?#C1L$V91r_B14CRWw%)(SnNC}$}_#AF>)B<9meUXB1G*Y z1MW(mXQDu>H>q;QUyLYPkBT|L*4$ zz$^6c7I5?C@$l?=O}Ngsj@4^@Xe7oFZc>_6s-`Ffw)ypWCd&}h*c{XQo1dfyOQaIX z2}Tp6@yTM{+{qDXLZ?nHE<7MJKKH%ip}LC9gc<#yV)Ud<4{k?yC#c9;=WW5eDA6Ti ze&xw@#Lzb3DUC;BvmdpTl&1l^$xLr$kFJ>L;$Xhn>YV^{%gXt^Dvj>OOy#!nui?ly z8!?%5mwk0M#m_Ep>V8--)6II@+q~-VSPKcgo^-xt@(#&whYU;~Ium6R51f6IWtLXe zlg55eB5Am&21XoW43+aUQHPVk#~~qEa$y8G8lxI}%G2}(gsC^!crXS$pVQ<+)#!^5 zCySf;u3I6{h9%v7y_Ik}YoL*PB)c9dz)k-JthrO)&b|ysFg?8`RS+6XPI- zBNbZ?)^+6t;mndD!OSeLMCOaBRtXz#3s9{{7+^HZW=~nO>aB0kjW1o#f*}U4tyX-1 z5OV4)SKKXjTT1Vb(2YdpNHSXI-n<&I!Fw9c?^$`=R*knkSO=fM*Ag$62YPfPjHrH5 zRAOF-fk7DDqBk>7Un&IxndtLI0|1w@4eYW>xDG|qf(Qs$S)aZ`K-bmJ9k^pw3SIa( zp=QrW^!R7$w+o@u)IajhX5c^EA11VsP6ZlAF8o+f%bci+caL ziC^8B0nj#h5eB=cxzN9K^a&6OoR%uVBE78E&S%}hK}Ss1J5i^~wZ0paO@}uViNC%XFhFHg$Uk-^%SQJI~I{ z4=BMHVs>K5XyT*FCH3e5t3PcY!y9ar`JcBwc)3m)<5vClb5a+vO{fSx`>IPabx3c|)mQ{H?mn56_%2j@N+PVZ_ig}BzArG^J=5}UcUOq8?#24TR3 zLc%*rTq2At&!$Bc%%;W!U0=Sf7W~JJ3L@K~QI{_lV7@}MlkWRwe$q(6orCBGJy1l$ zv~s?WW!P><11i~w2Xq2;P7_@rp?{p{Z$SYa-v9iaOoNohkl0DQ%%+TUUiN7m9oguF zhC}CT`quApNt|s!e~+a78@I78&W>Wdd@;$da*l*|jb(u}On||Z;e)`LTy{<09~jf} zd{5}uHOIy>+iXL-zcUL1j3P-%3AG%`sf8O+dIho7Run3a(+iVeha!XF!q-XROO7_c zktXGTHCU96Syik-VuHA1;1>)}6QI+Bi3o*}lypV8(5Alx-`~{q-^$p!#?|VHh=i)* zf-u{&%d50`Tru>1n?i4PB7&jTSm&*6!Yn0|jpo^129EDVL=>O!&uPQA2z2g_ssZ&a z3b!Fg$odN_2BWu`&W8(G%V!m*rgoojL48>dn5inS>(17)z`OTvNKSGlK7NneDNlJU zwRXE$N|ms{P@ohR37y%)j3%}lC&pC24NP0^ zs5CT_ZXLD#jcA{CP@LWrxjbaShSk-&+eVQ7CuQ@3k*pSwEqwjW99#o}7 zdpzOGLra}XkQ$rcI5JV8hf>!j*puH|DSm#$=&%!1lYm$`x-6W;%49O5@Kq4!K9~ww zpPed&8m}sgx1Qkpudawu@@7X`UF1JOUbJB#^<2z~yWyH*OZ^nmkyGtLi%~UpbmBZ# zs_|!kv;*8BTI@4@6IzPV9m+n;3>q5Ruk?`F5mD48LeNdQdi?q*pW%jncq=p8dA)al z!%RFC185$g4g$(7*TUSD)6dp}cl4n?_2II6E; zRN0f3qQ%dfP*;@~tZS7wmVec8OJ*OJPzwc?`2;^e;phvTR@PgD_xiQ){im`IZ#k&PMh*hn9nd$W{CP^A* zaAkKRv=j5|4jZJX!wxy^&YxIFVs$4wfjGdU4MqV9lO?*$+!{t*EwWqZU z^iajpf@{6u@ylJ@Sh=3TJ8iL``wuv}0@WCOJ~CkBfQA7v^2y6467q&P*V2k-(aG2w zX~=XXP9&H+K9nVn4Cu&V1yoZ20fg>9pabSJEdy%|@ReN^H*9exDn-md9*CdbdQ+-T zfU5Xs7sstXG%cN%4@(N`?n#WFwPt)|>82XX2}7Bek1-3Yi#k1v{9|sK@oJ&Zd8DCG z18c&pOog@k-QB$;S^bK2m}|6KGR#yDUAXO9>THz~3ds>EgZ)m_Ww^@Xf!X!c0Xb0K z0s##N{>(rB*Wk{IfCFfH17I6nNGQUiA$p&TtoI@76CjN|X~R~Q+*M{Ka>Oxp!2V&! zeT^q&E0Q^AxlbOheme4-K#??Pc55dY>cN;p~a*0~iug0R_wd=Ryfz$LwiYdYe6J}NKzuuUSGIbrL$iVe~ z-y0-!2XP`LkJ7WW*vpfgjEMT&&TtE;u7f3mZ#?{-*6PpzT2eAftk&{G!F(LLrRulq zK1qBZ73}Z-IHWF`Q&_#K7}JF;b?I|lX8g|470xyP>3fZt?#AJVlu#Yiagr>tis`eqV1)6^~x2w$;f`G8Kz;HQedzH!Tz&5Kbm)HR=Z;% zDL~a>Ce3iQ$h<%$JS6Aj+!}cvgQ3ygNlm~2qGGzwuH^y2-@1Q&?GBsK$bPK{t6iS7 zM5?$dfpi@a{F9Db<#Is;!rzsr@OG-`V2{CQ+Nzb9%I@N1x2tHrE^8OHLeTC0o@7CD zq121=hBOS#T>&A{qh4O~Y-Yz~ib+?1ULpw(7^WzX+i$37s>m*oY_j`~4gASY2E zVT)ffsRxMa%#AZ;WOVjzP0JKJm7mBDKFyOVz-F0fLk)TPJ9O@ zk%+R9E49u>$|Nz`*5i=aNb^JZZLojPvj#YuVPfP6M}jy0<@xc^?R3a`pIw7X5OB(( z&fxzfhM1SKGCEF^-Nek%NHt?_qN7DxkoI!TV3Y9ZkJ}P!k38uncUX$ zbcBB^r9|kDsH@6@*3|;^QxEJL1dffCKFFQ2HAyveHQ3-_gjV^o{;eb4c5n$noU)|7 zii8kYAZZVwQ!KRqv$B*Chvnpct^<1I@cme@LxQf#d{0u#O{vA?N16W)RN9n^6wwcs zSHaN2{*7}i3vLsa$M(1r_$sKwvb=UPJ4ZWK3K*EA|3>V;1*qE4QLT&~h`L1$o%mbb zSSJi6Id#d!qx8}iV zr-(+G2iEE90fV>&tQ?lsCo;ovgv5)~6D7v5Yo67Vyz*HhsQ0wG8>1dKSSIZCz8hlX zqS~{yojYBAxV%dvH4W@w6Hw+!PEUNVH2EW|-uK6-H{8=^w+O!_&JJmA5-_%-xal$B zf}$?L~0h> z&X~=-3v~akjQF9X`M%|EdDxxaa?JHXAN{l`eg7|#reBR=_V;l#k~+v7L@-NJFH}sf z%RH4S3W_HMH9z_W9^ht18!0yR^b?ZGCmII;!!lyw{cCVIjk}_<-1zYw?I?) zqvG{uw<~D?s78lmeWoeD?6#-wb%`WXX4cb<&2@KX{KBR;>~vL;N0e&dqTk{DR`2{- z6$#SmXa;F0e7dK?)?c7yY%ks3zLvxG2dKK*kW5I-@(4+M*PqyLM4NXvtWn+ejE8v) zq}czD$Co%QW|TX#;Q8ej-AQ(?oU|{)hvYst(UoZ_;7F*>_$Gb2_s6Jnwd8Tsy4k0; z&Ck~@FKH20v$q3^uM<1KFd4!rx_f@5+$JD0Wp05A1EgL$Zl1euN(n)~vPDDL%T&Q( z08>Do<&awbT-_mYkhFbq<&cIP{Zw|v%!Z`Yl_i4omBB+#R&6xzgbNo`_PmvrPLx22 zq;N z1iY#7|B!;v+bF=iS~Zp>JOZAy>MrHXdetLhC?a3X-#{iXB%-ie*obsHSd|gfuY^gY z6K#DRj{)e)QD!>MaMG%OK!_d&p<C`T6!xZ)iLbTPsJkkKU*)nkGw2gC)UtVBV_C9_x{`ba(>e>;Q zgXQIDi43x;Uk6IGfVQ9Q@@g6?jH!A-tF1%8PjIeVA}TrzB1GT@lVBX}**-f< zGrK3SorPjY{whLm?1D|nIxb(KUKNdd?B?cNC&7ZSWPnYOAoqD| zL?FvhZkNlgwF^}dy`-=%WMV%YR8TqCJwE_=(&OeAPOU-L+7tQl5>=45Chd?N2Q($n zn}VR45)_HXU9rS3kq0*fL}Lp;Yb5x8U!`uft@lA{BIH+H9So~EhMCz8+fR2Ir$_?V zsSY|&y}V6?@r>QvQD}%z5uh8yyN{CtW)ZJu2(xgNfSx9oD4dWe#!bmXB#Dcw_BKR^ zj~R&Df1%3Z$Jm07U+ez`dmiY9*Ua_SduC0RxiBwC1L&?? z*xa{X`+D8?u$(4zfzW3f=zrsKlF@INzr^`JB`aA!$=7%=9FT;b@VsIgP!mDxp8%4?m% zsy%aGyc3B%t#IFU%uW{<_d~2l^|+>Na7KuIR@&4tX9DgyMBShS2f|6hU)8c|p?Ecu zLBSFlwaB@}9ZkZ&>I8%IgNE?YcEof)2DWU#7bIElec}9J#Ko(yKLpegbIZ>-1t z9YRLY?kL9X1$GbqX+K>J>V1?b`l7Tc9t|3C-?bvXOJ_!avk?sSaj*yz$A*e-X1r9y zKyvlduVXo2lHg;E1@tsFbrqMpXREISMRj_mJ4(q-!mQDJ+0@C^m&+^Hc#X#ThFYu` z@&342W~SjKVNe+IJuL{0W|A`d`S9AKv(c9e4p-IHc}j9jBlMr||8yo6SizlHysBc5 z3*Vn~5LX4(DlTq&rO~I@Q9RL~Au>t)0Xl5%1iXm`tK#l%GTn!97@Q3yrBO-Jf^NsF zdUrr6^qZM3gP-?G^m5U|YCssov0=YhrJ#2?sQ}ZcE2opgl2k)QCx-uIlMV1G?c3bM zAs5%r%GEB4y@slwYc^sN*lf%tpsOwY{nJKE?TUyLSV32ogioG39#)|KJ`x7R*pb~w zCLJEe>j2jvQJmM?-tCmuvnGSAN^8r-evKFBm*20$m!OJ-XKFSDJ9BtQ7O#IZGY^Wn z-M|(>^zW9R-| zuT{QT3aFup-s6X~0fEHpi91Pxd^b=JRiv4(j_8FSN2@ zcP>W2-iAzzjtCh7w4MKWJ+_i@yL29}#Aq`w4s^XBo*bJW?#&$eo9tQP#CvQo+srKl zS|A!|txTUtWizH@fT(-Xa+}BS{yk$Bm?#QKUGer8((3Cje7}Ps_ct8lrU8^pH8h-z z)ZrC$h39{G4|dZoA?!Qo0QTkeZBv6-kXdrObzLO|j5nK8QX%}eDcJyUrMH+M{;){I z>M8)b#-Bu7k#(c^LIxqfjW7C!y1S7@plub@fNgtmtKYbm+8q7q{voUC$%NX5+Qi2l z%Zqa~oXM=KUo!8T!4IBkA^Kc&VgGz0{r_ROr@#l+O*&-tD=%`#%0?9~p3EuZZ{r#l zT4^5L*Bl?sB@!<&1%r@r@axsuA^`ncGtk>Qe^rED%FvmzNB^=yTB|Za$T7;D1aDi& z=>*e3->sHJ=h8?xXGt{Y);*QVnzEa+Jev_~L3?E!d~Ij)9M4;Qo_6QPK$f_;+oS?& zhWJu;Igz_=atP#hA`ckMK)x-R&-vR_6(&@;zX>Jee}V~uxa#^8cW6H z11`3BN;!9LhlmKgLfF7Gag~mAFhn*Sm@Po5q*GUh8Q4V&dGNT1SH@^~O>8qTg;M<^ zBszv0*bqVMbVDRQur3KsVoBjtJPa^NJc+^#g330k+?}}bG;jIv$G`~{&y2+9kT|y? z+jL=upg8)&tN81iVCm}Yd}L8|1N76uCVu7Z%Z0C76EW7bM(*ediIr7Siu(&=fP=Pe2hVBFJ%`GUgH zdGFnL3?v0B@}eq(tB<8)rn<`wXoXtpps-p!4C!tm6vKWQ+GkM*&4ISL5bB1GR>nY! z2JV)i-1zygnx#C1&Q{s8Rpers{Htt*!*E# zB6enfbHpJg*f2B2{5&nr<>>cFZ(O0rD)>gzq4+8 z^y&a}@%npyJ)+;?1pcGr+ewoHQQkw-LGY~t|L0B$1m4#_4@OFyfDA4YxvBPaqwVQ< zC<}`7)`MYU_$<-FC(%_39WBXkj9vy!ao=CcH?Dz zKkRuGl@hiqV|8*K&I|oJNJ_3vO@8e`6|R&86o;HmmmcKGXH}gYRx2J;46XDaue{Ex z0%>w?tGi+gr@)WqMV-{nk!k;_>sqj}1Cz8npW{8=)h zbUkx1KLmaumqL+;BDMoSSgEiqF)gNOwirOA(M=u+xl&Ne0doq(7eO_XXfq;*xVBR>%}t( z6mMDE^I;C|o(zue0P9ARXj0ymD5F!2yf0P;{(!}g5}_$7F<2!-G3q|+yKyQpML=x; zt?yq!z5UmwKu9$ZDJIIXDU6Z=W$RJ;^5zDc)R012m6DqE+qXUAwJvW`KqvI&-suVs z9^|LVzftAWUG7O<&;3&r2M$;=6-;C$h&!Z=v=bWKdI?N<@PCg z4?7lgp-I}7Z}#LLWd2QB^Ycc^t(3<$5N3=6RwdPWfb4RIK{5r<3u+d9>^ONLLwhoI zoYP|C7t?zSk4G`}meVhfX^BLWH;LNO1CGdDyjn^`B^8u7iKru~`-VT$L(- z6uhC8hRG>)Elj=cJ22mTSS5x;opI4 zIJ^WL4H!`^lu!A4^X&J+#+=rCN8tKJSV*gh#5-{BEfWU`s<^JlsYReZ(0~nnqh&|G zjuE;2ZzKq$0^8a}OE*A97;!fepQ6&^JV}hbSgFZ>% zDr~w`7c7ChyPvQI4YwU}!s28Fj(n;gLm(kjlwU3zU4fVYog6+Z)9%?KZoy3t%p~Xu zk}-W1F7X1U&fd)bPJ!+EGDh%d(>rTtV|Jp(N6%6_r}~?CYrByuOKnx^$(l*+uq*!AsAiPjVnQK7&wdY9#r zh!G!WXp+;Mi9DJ4jVt*h20I#Ik#CGd?6G@f1K<%bSl7F}R0v)-xm1h<%4vY}vA-Gb z?S}A_r9QON>Am@Z1-STBmr7AaP`bUSlXQ-E>F0@h=z>(sruc-De&S+&=DxUQN!Ibm zj|aJS4+p2xPyrV?W-4%iCP{l)+|Yo4=sN6U#MTWXP~^lh;XsQCs4@M8ns~IYyAC%l z9RvnMwzDhM3}jfxZD_dZ(m)Bkkw8I#dRBt_bQST$9YbTkLcDF+tv9^`%%&l7eg$U3?JsQG)C0P$U`rveIyFxQ@$fDpTPH3GBiVxiv?Y8==3{1htR#Z?VN z#5cnxvP0K#D7SXucnv#VSj7&`TPlbD>5%xPVyTQHTY9*`(GE!$V*>bL&3mGc|B2qT zTi$?B!G(9@$sjW{LsK;C4?A1q-da#yh%6kL%qpK*vvR>P<2c(amguYxMq0VtRt35= znC4KTZP62LPa5D0{Z9&jcwLv1CQ@#yJU*&m+^bGL&UvgV)0&^nul(7-) zJI=E!P2`C+{KqQvqCt;^8PrhG&($KYq_RxDY?D|(NptsB<-7fdTWLZ4S)4AsMACU} z*bI0k2Y?rtT-4(|APynLD+n)btl#fHVBfu1DMI}|mq*cD;`ku#izIdJ-didCFc4vK zMRMyNK3(#qwKIi3WV6k}nHZ4&bL2JVFEP48z7v!Wl86ng9jWs*q>zyecREYOZeHb0 z#)Np&(#=R{VmQ;6scOAjUV+YT6NP~6{pq&hXWzieZp+pUFqws6F=7F_jK<*ZLgDEY zHFJ6Bn&Jq|1irtQWO<~>fwUh9WE?qE=VTSLIVc8pZ z9Ewm49Hzv1)%iYjJ7jaWlRDz9>QPyb79pd?i+~3_*-}tJMoH#|IvksgV&kGeg*D`o z6}Pwiz49bhn?(j{b~{x^j##aCMkthEP%gu1E`X+f4db)%Q4m-|Kl32z3(7Z$a@^7a9Mx_dp7Y$YvG$PZ#h<_Pdp=01qyVD)-ce72j*%3&ji3ZUnsiQVySrK4?BD#s^XRW zYDEUr$a%$CQR~ozf*RGMs-Tvv6jc2HI7>kK-mFL)wQ2L(_+PA0*+Fc7k7Z5hQ(28z z0|n8DRK?4(zVKhW5reIBUY-{5{LhwLx{k+hb*X{V%h&K+#BdfCgURG1y>Cd~oQ)i~ z$4wvpSe%-bI=8{6wt%%eSO3Fi>-=SsK*nnuW%h$QypRO%tSKIxRP9BE)5GcHQ`Wp9 znV$HzxVcrksh;y;+umhaOOOH<=@#=P)M>n z#(<(Amr#_y7zH`r3PXd3&SPPrBMf0snceK)NaRzQ>jhpXi|G-8wGlOn(``j~U_ki> zT4E7YDG!6vB@r@#xA?qFRiHK%@6OnxOeFQrE&%?!qKe?R&ssRk7sPk2M(}9 zspp?}0@*Em(=-uH@*Yl~Q*lQ>>8GK=WaoYYIa_o>c0R~KH~E9nJfh~# zmX*|@qukN8!V`uB<=2mQ&vnGWI)kVi4*FvzAFMCJbYgWB4(^myaY6SV;R;h$NW!4n zoY}uQs$e!OXakzsJi{y)G0aNAA~_=kEV@Sx(U?IlMNxHM97E*a`Ng#VL{A8e4y*H} zbDls+`r^*g1(!3KC~i^yiPV!;_fct#w8Cl|u#x~X%nVg!uU0I)=bWu#^{W(p&z_Y< zJezzzSoVB%n@Eh)i#Q*LXl$;9Jo!`!Qy4Kx)St5SpJwZ9|D2EIml2YVg^cy?xhDkw zR{LnBwFGqbOMn;_HD`vOsG7UD{LIN74Filnd9(X~(w5~|;p5JZD#$>TEa0Jj9-V zv&4^Btak+B#vg_~=wVLuen7LU@GC*wm0PM6>>|T5+*?Ej<>OIJ=JGsytLQ2%U{6n( z2be}4iq$RiyWA`gL`f?wfNfTbqO5n9-a@lLj-#{IjHbqs#hB>vsJNz@u zfbz7pxe=O%2Hc)=)XK~}Gvg8S%74l|ZdFy*doCIf_iLsY$_G0*Ikt5D3gx#)2;qR* z@Sc(?>y6>EoVpAp1@(;G-k>V%-MJ2Ti=TUI=6F~@(b^xxe!4=b%bBpgy)RzZXtVGi zl3U#@5CP-aW;+4p@cfr@dnq_*)~uWQ-t}y|Mvfaa0jNI?)$_NIOR35Trbh|mJT8MB zjVyx>0zQ_TEd-!a1MCCXY@_Y;GHeKpa<*&b&SF0bf(eLf)-|WLQ;>O>{?0YxSa5SN z3Wo!Q8d$Q|mJIttEHNZ7HTsU)LU4344JzEy%njG{hm9sEM(uOS>FD}b6wiM(G#D40O#%C`hON>?#>TyV5F2&?@m(B7`FZTftqv z$5Rg5(X7}=V#2MhX!Qfqtj+0D`w5t~yIlQ-ih|W~swXYO7EV5sw6*hqp}uj7oYHnm z@Zr_;w6m|EbpGZweKE<-`!ozrf|BNHP4F##ZQfp;N8PRW5xGyF>1qDkcQC=Sr`(~b zp)@o>S8HQ8>G#jRslFY&qor}JOT8AcPsk~Gu z2ZMJy27)hiu;Q#APGkdcVjRc^a!jwYb~!?_)A4(T^y1ZKO`Hz*WCLeLRJ8uIiZ>m> z{L*B>7w9|aaS}(3!g$+1AEH%}9N{mtuO4sD&c~*pm5jgu5wq3K3U%ET+vHFx z$e6p1x)m^mL;ndV21#@ z5>!V*F(E~e6#=S5Ye&1{(x2J%lOL(N$A<0SfX(sdTBPO1L)5E}Ht(W)9d$Ju7qiBR zaH|x}w77IVuUqsVh7ekzN8-Fr__Hz-X6klzV7GiCocF)#K>D4`B;M~9OFK_%`!o&o zjD3*luuwu$e+b_)pSj$!FGzshLuhy>>2HO-t%(01eWyBaVQ%X$>@K%4S99xR_$o`h zbZjuLpE-`Md1{X7wU;HbwBB+12wQSZa(MJXZRPjGxJUC_s9b%{Z;4SoLN6|KUYb=x zKA+!}P5HxlkuX}a6KW^2Q0sQ0N z1!E$Sx#}*eo$frdW>cSyYBrF?QI%C#yb<~lRCK153_9XUCQo;7_$V-h*(T(+W5@=^ zNytCeCLlW22=*doCgkUxt>M}D{H%sd>@LSJ+BSZf|F%XWG65e8J;;?)67R=VMDBE3Rb*C#fI8 zS6ku=2tkZ~)M+XB0~kc+4AsBSpK0TsoNI%1pQ(wkDI}dk+1%i-K_OHp;PL%V@7Dxn zmrfJYf5>D8ut7)B7SRXGg1UQ=vHN(vCCl+P3f`&)x3?5s3??&Cd^9OdGf}}7u{Pgn z&{Mh3Us67J`YGmk2aHxqIuA^E5nU_zxNt%&I`AtjT;8F2JFqk$N;Oz1GYY60j~o~5 z<817H>N~O#+!!tvM<(&9J_j65GL0plk$(|=CEhV^S1RZTt{qGE*cApPLf)3MyK(omsi@7vMw%?Mq? z`A^xtZ@`$9^E90 zXr?$;4g8BPl|hHn^kp`7*VY`%;P8_6!>v>= zY1#Hp%}iE%3EN(YV)hAx9p8(tpn3VH$~`G8RTbIzvu&0145NM5Hj~%K=pOKW9DY64Y#N#L+plYkX7()<%59U!;}&n_pXfru+@ll1HJn zEs724zhZ9o?arflG`)*&_*B8c)OOkNe3yyJoGlvuGm(B?npK`nJPFT6&z|(1y@_j0 zgT&J7q2{zn(a2_=M=Nps^HY`vuGD@K9`gHY4+dH^izIyoWof5^3~NRdGtEZKja|70 z-Rq%G>AC}RPXbyi{Hdq^B{=d)iO=%5?P>f{W^-%kuH~mCe>nfj^F?jlVk?n0;*OyP>5upnG`;J|9VIm9XUY-n z2DVrE0=V1X@C*&ImubJ~YZ|T+~B(fGaKy`kcgZ&>xu6*Gy zxy-cM=;SCu#m|Yf+WKsTVHLK}NhgXXEekGW# z(yByHw}?qDdK@!=wR)$%NZ*Ump}w(aX(er;5!fbS$axfF5*Ed`6~|!0@jQsj>M-d*;am$ z5GI?21!wTUbP0Vm3&XES2LGbzn35kg+}THkG+9g3&yT{& z=!+g-+n8g7zI!N&+mkSHGPRj_k_J`P z<4816+(~RvEY)g_W~Mvk>jZ@`i0~DAdkCjNZNaxN^*-4<`)VbHSCOt}u4hQ94T=zq*- zoWLo0m&u~hTq;lnARK9xJ@ph`veufFQzlXluTcCpBGbxJY(CV#R9cstV5CmsT(Qa{ zSr0RY{_S$F&5wTw4|dMP$@NYDTi-a1rX}_RxPxUohWh;C0M}$+)m0PPmC0oA#(-@o zXPN$1?U-G^hH>m{@=_h?f@AZrY`0wX++p%{Udnpq!YzF8EbP%oZO+(9uc6|ThM4Os z1|ok=0PgxRqZ3)nA09lk_lMb44i>-j&=v18(ww2gotj(lV94R!#+R4-x~Bv*|L%P=_YU_?)||?ZqJ`IB_lvBdZ&8q) zAruO1nIqdccDuidx-uWJH*MUPQE9Rw>y=kkaTz9m<&W8e!XcqZ8~!V@(b-W4Rq@3> ztj@ZbVh>ka{eT?wPpT`Yj;%9@498HNi=!T6l{S46n~g_{$1ppuD)98uWCf7)-_cd9 z^Zo|r6FxQ|2on4=YIW_k-#nef5MPP&P zOPhxc_A-hMw?(~_ZOCwE+X>Q#O_)XX!Zl`c5&E{V!p&HJtf!s-X0M{o`gXphpU-KD z&6W(nd$n;a1)sg&v*r*42_Q*WDz3BkUBtFW>~@1~M4f9u8xN(4yDVH9Dwi%PX_*7S zs0IWEf8b#YhO2C(aN(qH1)7Xs2l%a5go}8^*Q8rcXBHn0Q}RoB5Y|epXiF$;#nf<* zs;x&mifQT!YUA5^W-m|rATswu!=67E{A0fhz>8Ecx2Fdl%6rl_C;!J#(`KfT$A&`6JdvYpz$%bTUc!m)Zw*WFK+oXiK#%B^oeVBvd;USHu>XGx(KLz_3p z?DK=C{Q@dWg(H+RlXBU(qWX)`hPX42G5LS2RVD{wT-1ot3Hy~FNBMZU)nKdgKDlNg z^+P>K-Tz=f!BEiN=6ue7n%S40DJ{z!q`kOeTf9QL+3X=28CQq{K!GrwFq9Gr44D_h zoxMuWlGof?`CO*D?ywu7CsTK!LOX)>Q>d8+=WDB}8k;>KV^?cXmb{xHW2HSki$LIW zQ5-miPP4XYBe!LoVF96iQj84Q>5O2vUTjW?s;Wb+Yf*&Uz>sjpUL`3Er-S6sE zN*X!c@+n+8vZ&W413yqiR<%M0sM=U?QB?NxSIwoeo!d<$N$ygYWVE{1% zosKrb`9yG;%fiOip9MTTEENxijh_b3a~TkH6tD?B=4Llq**#HvHd+ajE90T;^6~s{ z-4Zm*vYkZnt;IFI_**#XrR~x}?Vn zc!xh+EZ)3zC$B20U+nGBMzy%DL-3Ax#N2l@adR({Zt|E2KO#E#@PMP<@dP38hfEdw z_v7F{9pID1Ss)_5@S}-iw$GYoCld$dS~EZ_5T_rdYT32j2zZxiqYoj>ZGH;$;qNk{ z={S{HvuJ&u*h9-`f5@lbLC9xr}@zG;Aw;e7XeXgm33HLzBHbM8-))KhJ_-%Bq=t zx9b>WpwkQe0wv0s0X06_bhI{ZP;p-@Or|fnebtnIhL6I3e%V&9#zL%ci3!%ltQ2I7AXFq_6WjM|uHp0l1-O^DCdm+<5FaBslT7 zcZbz)KoR{Jb3?M;QPCZ58RekW%U8L|rw(-3`NWX4eYS&f5nYk1n3WS(6f`sE`XmfQ?!ntrUp{r(aHvX zWy|_EJ0*|UQEI;L91nK7AoF;=j#3p$KeF#P zDe91MglxeMms#~3d}Aka{l=BXUH;%IHh%Cm?PkZ~V9Cytl-CN?`z*BRT$n1gU)0$k zk{ghdyNQ5cuM~9*?*{ki`M$}KFqrbUS+fho(x=p}`Qm0fq&>|dr|Os1KV)1B{ncoC zG?AE_dn=;LywleyAP(C`v!5BU_Z_X$Hu0v zioFggQv%)Qnj_0{``O6E!Hw1F$7Iz)_@Rv>5q?Vxyb91Mq86$RciiMqYO!lsUbihH zhxWU{&JuGpw+Eyxv&L$sYi96e?ZR1rRExsVkiGrcXbc>NcFSM*H#RYDxnMgJjXh<7 zUyFRj{`Sz33YtRzRi`Pal#&Q_6*Kz6tp^yOmHSLu4p?QMZvEckTdb#}-eIlnM9r1$ zZ{=U1TZ2x?K*;=`Mfl9j_9@_&4oUOe3 zg)wR@6sfwCIcx7H2JOs;z_VoJx3m^c?e@%BwnlcpAG@}{_^!=#l+?Q~&S@UA>e*u!&wYkD86@fiSoH$!k^=0Gej3INzX%U#5Tw@! zu3C>|{&Nw0)AtpTWKTYBv^dPoj^fYRGf|5zHy`&McN~pK_TvBq;UCYwj%#6ZL@<9|NY7;hx5Ln%jZ)9sJP~0{ zeNIVLlQR3pry^zV2`hKAT7g^o+}Qhks6LOu#S;cY=44s#w+I^BENciOUwf)@8G&@> zP#-42*1Rvjmi4v{B)uTj`rMZG$A^!sf5?WRL}$A7#ggWaLKpAxF=EGg)~lB1qUXwL zU$c@DE7lC$k6Mg+&Jll`%#1=|Q(d-^rbW){y5pplf_!een^>w|AfC4}6+b&w8oGVV zy>XMl(u!!z|9fMPp*f`GNHTFC89!ZnzM2q$e8y84gJpftLLBR9RH#%E zkJ!7ONG}+5jVEg5%h`xc_s<`QdmjSGy#q4Ev~*E{Mwm=|JOEz*(ymumS9UrY|9H-$ zZt%0@zFw)|`G6^Nat}+N17o4Nfg0URK&?zB)my|6tC%p_RLhEskA79n=4#5|Cv3rL z_45!MVG=3n*4vfLV8(bbr0md&=u{u5s_El%#!qp(m4VU~+DhOcET{9nfhdU6hbz{$g)CkqjG^@F;pKX_o>E8cxIvN9*2bb2^<7cd0FAOEknV`QBNHf)? zIjzZ$mU-Pb=VRZ*mklyU{(T}BZm^<5f<*o)2+?NQ8yPaTHu3D8gf=b01PzsRQuHy& zv9@g|M*Y*KmA2G{v^P1f31bLzlc+c%@#A%%r2dkV`yvvWUF#mv{R(2Z_S9ZO1C_(B z`y*s91h$wDp+`xxH{2AnRvfcHie7cWWL#UY_cFP#x9_`SW~aQaeX8DtUO-@ho)bpi z+Bz$0r&sJEw~sW^LH?c`$oy15=!K2G`zzeyq{B<3Nsy^7t~M!_FI^Q@H?vjsAd1*^ zX$5%5i1rL-&#|4W5gT2!cJM%Mbz5wKSkFe4+P|yOs*8_BYX)r2Z+7yebLddqBRaA6 z55zvT^urkf!RbiQQ!>hspX#%UMTu)6ZEI(RDfo+ zO?SQ@7LHUaOJ6S!BGe-Qe&*I$`G82NQC^1s4B<*w6-RD=O4Jpz8ARGk_1UIXg-QJa z45!ILW4Lj;HY(vFVj%bkA>_`Kn8Ujr-A#I+k|`*^-dU$$CxmzM?B~**{4HHjQW-=- z)CbMKc;8$Y0$RoV=v2drgH*C*lh6gIVoaugvr2}GHnUDJ*Ap$6ksqG+`kYAeF#Ktn z3o+Dw;d9q7J+Fr;5EpY6|MkYZR#Mfh`sxMsm^RuuLFiV}%JoAspG4ImVbC8p^RzK8 z8|J2C5k*CPg?z!0NPOI3F3&;m2D^7%U)p>$ib+IgSqjVqF(ly{JS`CB|~Em#g~Ge`)cczSA+{yzx3#1ayH!ys2K@*#NV4gaO^Ez>-x&q6d)Vy ziC@3YmOLC56!w0Z>`C15G?^2S-*WoFVB*~^Gg)Tbc* z&gpCSMXmiwx9?Q85eRg@>$0)ybw5tl=WoSbhCaKVz>E?BPjPUc%u_mvo>t4Q8ih&l zf?;I$=Zx!88tG)+0=;u}d2Tsrrh0z$nE2BK^Z$ot%>LWY0<1jI=j5kTzD*0#lQq#iN6CadtTHj;jD zyuQ3#b<=iQO}r5eYA|QwF6EJibcV0&C*HWYQ}9Dt6*t~O74!eoe||myLfgas_=drh z?VIjG{NU?E)$%&k^9;f_8zUD%Sc|tyK|`Z=I)+4I%VGdT+nX$d4-pnZ7D>sPgU{v8 zu2@$A`5HXnKom4BC;M?i0|9;`cr=j{#*H>IOsut&zVTagP*yPk1MLQV z;wL3Tf-Hf z?tRTT_I3PEdx(oN(nCr z?(3$f*Wl8xch++zPL3U-H}~e};_E-KPcU))Fn?bwV1XlLwY{KUXjfZlvTV{#6JGxB zGgclx_xnDMKc##*B=Q~~X-7tsHnvvWrtTr@EGM^=d?nUxv%!q!NYy$JJDkKEl_`fK zyx7aAe;bR{bXufEqOjUm7Bu(rnX^VJJqZNA6y#r9?>$AcjBxKG7&TXmOsK!F4yWl| zh)jqu!u~ImA!som53gBC(yjl-Z~xsACk`tn32%b(Ch!sp?W@+DIcywj`QUS3+;wzg zTuoL6mGG>ULl)OIw#%LEKUbBTwd@b)O*qRs{-0cBDJ~MU5Q{2k-_Wisb0r&NXt9y= zv?}hXOc%yG>l434gbcb%shYU`VB;bC?U@eCK=s*YEfI%?D#EQVG3^-(mjrD2?t5Ag zK{7Q___(mXFzRHzI6(9UEr(w?uszzluq0|;i~H83@2?wD&#Pq3Wd()oC}8l@gehIl zB;m$S*GxFLe%C?>?(cf+Z+keHA#Q&Ve36sb>7Kk z9JkDknM_i5y(e-jpuG9tS!x-8S6@VWsImtEV!UmZV+Yl9YxPM(_=1(Z2y8YIr! zOGRMK1ATI9fJEvd;kAjvACn`WOMWa!A&0DK5Gm+%UwG2yw8wjI@>Fu*6a+nuQ2vzm zb({xd_M0~av1&$oUk4Iz$ngx= zk;9boa{59I)v$L?i~|xs1S{j~=Z{*Y=rp$E=qr9QR0GDWf-tf`{~zx-2_WU8^YaL^ zCCM+Zh=s_zU$s^*$9_Qbst{rOPdKttniJrYaX>X;E1pXFOU(8{+<@KXc9e$jR=hcV zRscsi@MssQf@Syaq-|#2$MR|#6uQ5LE-|8r)J4m zH`-$e|FuKr4QNO$y{!Q-{cLQiV;6V(ydY4^Gzj2!PY4{E+Y!z+9xul)<(V!%=J_80 zwqwXzU1ig~VE7zA&I&P_SidCTehZOHl*xl0bUGzv7uWg|2N!A{=;&cH;A*^ z#L1R-|OO3>@jRtQU*`A$L2kN1&4OJP04w`@rI02WRX83 z-Pu_x8CN_Y&cWB^t+`+LzxF?TfF_Up=@rBI#8Mf0&5L^$=tm!&b9W7~@pd;0^g2?h zWYpWmT90e#6a6kCwi^o3wH*VN^YuBiB_?l*!glk9CM2* zj)s2T9*ca&XD@*P3=ML66h;iqvzrne$D$hdgFo(u|FK1T^WtS=hqG9%ER*`NkdgLW z`^%*-(ta`bbOf{y21C}=+7uqunRxB$X5e#|8ZgOghlb%NG@;otR##hP^s)wzd!$*$ z=^avGxxQDSLEmRYq5;A6_0AeU!L%e@Eqh0xoSm9-b&GP8qmc;(%NZUuC088r=N zQHR7mk*fxp&v*5{*B&g!%J7+_X_6^(Wg!j2()VhGi$9Jh1QF~ekUX6{x(!jHZyHqE* zdWvAgyFo$rHq;`6b%tMoC&4j;8AU)7?AU=5L|;Vk*mMv=dbn%x%?5>bzE#%9^WX%@ zoXmk`^OD;alz5Z1ILd#c2lW;WwKQ1A-c#~OKvlLtvwj?Il-vDMYvbs&bNQrm)VN*sQW-r{2SB-}_;4pkj{Bwf?K zCpW7+>9hG?@M*x9t%)eUaq!3T(lwJ8BWd_rTC}nzqQsP+CqXo>0- zZLvTB6}!I*R}f8DKI*Xn@QXL3@c$Y37QTJs($6vUt&G$P2{LOr3bQ&!oqouyRnXTm zr`g`{J1O=USKJ{HU;ZjpeaWGNqK_e^to{c+NNoz8REFjrUxa>qBb|AO%FYG!teQ-GZJb46f(+9a68yC&ks8mi`do041_4W8bt%n_#5w z8_w$v$fkDP*|?PL;DwXnI9~AB&_6}F9$Pq zY;bI>wWb#JIqg;ZdZJEHc`=%WrPeQ^cTigca3s&vA5SXGhceb5RJquQ4jA6~I<$ql zJ&Xp|5qDk!!1>|w8r)Y2#0A+!&-Y6#6>EQA2Q(L_v3lcCF#bFK8~`MZcOVhBWw-$} zKx)3lnNkwpe#3r({Z}KhajPb}*tb)TfjVgr&U1%vhf? z4z_a%uuaz6+>;5WINvFU#e=m5q-L#%64;&n>5U5KWH@L%cfAxQQ12<;p`MX+oMZk3w9v;{90W0P?*1ReGTo;OYj($3-z5|4 zlD@JKp^_;Jb-WFoJ@4eoZ>dPnLE_AT;Z&#e@v-7SorVSkApGOplSMi2mSDA;5K|%$ zUI>Z>ZXD?S-bza259ZUGlcTdvJ7Y>4y#QijmJzm(-1om*V*E6(ReV*4gXl$Ex^t=< z2z0wNMwxExUB^5il!u=<$%w7xGRpvMtkY>^;tYOk@wo#;8%YL^-^q*j?inU4N|OK) zxD|XSQp03f!%RrizLu7?Hb8Ws!xb&;JSL58mz-IF|BR}Oh_BnmpaMncB+XIjX^+F? z5vYvCGME2Zc5lcRyWQ9fsG7kw*SotZV`x{uJv0ZrhEoNHd%d6KcZ}O-`?_0e4I@oP z5T;98*USFt>cueVo!MPf>(tm1CWH7e7fS zl9dUOQ!GZ8Qmt0dL7dgp83A(Sq$ySQ(!L~Z^oKH|twJLTaGtbf3O~s!Hb&-T(BgL6 zmBMfR&ITanu(PTK)u#Z#dD#Mh&b_)|F5^sAzhvWZ5P7zy&X$HK!KlWG6JcL`JHOM- zdlG2gsD+meb`pq(9UgLJdB(}i)Xf2;Vav6!wEnS-lw_o;g}9rBe&0Sj{)wS=XyfgR z^$Rnh*8Y;61uay<&9aGv$GxiGL$}nOdvZu-=N}s&7VA2=!+OAddkk~xcXK84r<8+7f{>$;ZjzeYT7~@a>~-Z zVqqeFqT-R0tvE#I5s&NkXQYm7qX9Q!k6^zec|itBkj^5aGMv#dWgx=yQ(mq8!I^{3 zNkx%kB-op1&w6%RK(lnPWOC3CQYpS^Yp@U6Uua3;Uo#1R1o!6);lW22T0H0{FeTNC6IW zP(|Me8-%7PatFU!>&kdZ4ag>RnWf&${NbC=pr+^GjaRe?bV8pA_#5%*jWfVsE{|yl z2x2upH$ZOzIjw))^8p}@>^gAM$ywXOmvU#~PJtnd+jl~5XEGp>qElV)38?3$qfv_j ziZz}(UgdDW=l{(@R>taGbnr{vjRP1uD;{QTwA2w5>%*>~kOE*gSu>Y*Ijog2i1GOn z*Z^iFnM6cg!_pUME;hGaUk6kky{m+yM(>dsm?14|H`6wZ#Rr%B zq?Gn>J*M|%ZwwqnK(_?FCK+3{Y_X`|iVm(*59yEk(r{!;S5%0AcE!X@a61G3JKi}m~KZa536K(YnYeLh-E+L|w8xXa}|xN|3${5w$$H{kkj+gl&+BR~DG4@Rx%yYNmVxc}JS(E+rftkAe?P{KIe0 z4h+qG-E{GY-0gMBpOC|Aj?#eLJEBBglDW&#tR%?1yI%%IT3oMl;J@vDr%q0Q_65^4(DfflhJqr>e zH_N86CnQ(Ucb7o+cb%ni|6WQZd(RL;a|9hvecf zctMnlK2ggsFEeB zG~|UMfDaRfdd=#7^2CevG!CzEoTsa;Q|(zu#oTXv@7<3epzFw7Xzr-QZ3XQFSJQ!` zU%@>SkBqN4e|ppXinE$8Rr33Mud?Lu%li}Swerc(_~X`pM{oJXOzeY5Fh>ptK;iFL zvB=KR^_&b2R;PHCl_3psG$2f!)lmN9su4t*{+&*n|3{UsDir2pe&m|G`n1;!MKsIy z3yKPr+hU9kjZmWEZY&mf0Cgfg<86Fj_Ca!+&k?@=e+FZrHPf3?INf3HUe`_LuZn9z1!gb=Xdh~X#C)aU|{b0o>zth_uGG{Y~La~YCp82 z-Is)g#Z4>~)DaVptg|!CrEB8z{zzm)@Q$c;-k&xR2&R-GB<+Rxi#ncFOTR1DjigE7 z4OC5DA_`KfX(GSz!QTy%&*@&7*s`ianurL*EKp?SFpOgL@kKFZB)MUn5>Te=0w6yd zCV6WYZmqmuUn?E-D;e|Bg!~TdIOU227Aj>yWq1ryj|aP*kgC0awF?@Ee6a6#Idxr< zXc{=@4|y#P?^gb-(97fiCZF?lEM-+mdW9@S%K@ij4SymI+xt-~_j39_pY{I^i^2d3 z0v86d@p4M}uu5@P)<@0QE^-{dl}o2*$6hx}M7=(9t6G7L{CD2Dn(=^n!u9%YD2@^+ zPaoXso$HA7s+MGfJc$C|2aenkW+9rp7(LSgS0S%{dGNsf)ps=_kD_Sw3vn%t?tyIV z8stdeO&G2-^3R~UkNd1fgx&b;gBY9=AhqerBiUmP<`*qI%;#`m|R#~I_9;12+{ z)D9Rp>qPVg6f|%a!T~0&T*p@5p~t>1GZ)Ye^gB{{YOYAkY2+~rYud%%D%eVc=qw#| zid}wIMW^!AsMAqK^#f;v&oFtqSxL7b*GXLfW(W+D5M&W$-j8pwce`FaziVeUKG8gq zlnfb10_P^eH4Ab1wdCR*v$Rpr_eOVuoK*`^EX3BoAXl$MN%7T~h3ogT3UG}0`f!EA zV6mx%**`KTdX&)C3H*zD=N3W4RdtQ#86w&TCx%4SFOMNR(ryOIJg<817>OM~wY$eB zlhne=Y9ODgF@5{*baZ0fj8|M~ZT`t$UKM9kX+3)vMj6aW5YCfu=|h^>1aO@(g&uPr zxlMrLfNmwwwk(atpTs7DskOuzA5DWA4Xiu?SR?7O2Mb;>Dz=M|v}1j}(H_Dc(5yZ* zTqDoXVyW%A^Mwkj8}SVYz_#Sa6-!^4fHGnkhc{oMG^`k7A?`+ZA5A11|Id6~cA7TE zaJ}lN=O4#zy`9E`tkl2I>^s)Ra$4zTQIKX-lHL9~4S)1|Ip1$APMmValsA zaO<-*IpeN_qHEaFeGvWFB2jUqyh z`Ld88coSY`bKl=`E`vK~G9dszX)SYKIpB=T;#IUrq7!gP&OyCTp3|{Y)#t>GzA~r< z?Dj~&yu`a$h;ahvNixN}1xY_72zCZt9Z^1l$a=Og;p^<52_D=^brSE1Ljv zWys1&HN^@D9h!NHKG&lTvq_oYnrOW-z@b3}kSye47qReH!Nx0M3x+4+(6aO@GQ z?dJKBl)?#qkQ}+c8Fwa$;G;ZGD9p=8eGym}DX#3#Y;ZJ10wLNT#=M7lA8%PJvXRA+ z*e);yJ(4Y+S^^CM`3Ca#6I)guO@2_Sy? z+o|Fur#e|T=WD$z>KJNB@;335YuCp*P}up;fQ%ZBG!=r|Qko=)nqTH`_5IQf_+b=E zhb$;qrCj$n67nY#_Z4I0ziSJZ0P;t3xccLBA%{Wrh0zy={!G@>H@%}xyd6U#MHk&p zEn)t$fUEY9mUQ{*(6v#^W=jrydkLdlBVV8ip$%XYh~^TcWJ#Tq@AM zaBwCYb+%EkApK)pDX+c^^4r;|d+qFC(9cS`?yja~RL|oZ!Tk!Il&X)jIz_`*=0y>q zxglTD$?|<`ZQ^bR_p?dF$Lb}!l@B7{j#+m)m}Nl1Z)*>Pl;`5#Pj73Sw;xug)aEHY zjN{GJsT(*Shb96b3nH^R2IlRR9s%0L*oeTh0-xG|8n@U$`fy4<#mrNr?*MXQD%@lo zz0n!^SCeNBU;wMfJ{4nk+P%O%Zl7SVA37}P(O6hU0%94WE}VIbVCoK$=nQD*hk2-b zB~Pk@{1P9zKx0U`|Ge=NANqaaj0RQ2@(VkcaN-zbo*_EtUjj%aIi&y%wd-TrN6u-t zTYrM5>glocX#jfF=554g94yDO#-Fu%9vlm1iH#OWbPwRn3jB{XgS*1wP|w;JRx;1-s~?j7Y#HT3|N8KQ;Pna9LV#mhc!o{bAf@yZ-5Vg z=qvZRy^7)oZA;DZStr`!oNzF&Mn1lBo;R@^os+0O7b>AOii!fTQTHOD@Uq_*pba)$ zd^-O|c(fuFKgK7PS4E0%@|0(UGgWN53Gh*Av(+nsz;$0CwWKxQV+QlYolYmzKWLt-HZ!2j^z&(FmLuw`aq~=c=ysAu6Y;h zunSCLf}}&IiZjgx#zsHZX+T46FM9UlK@QjcyraQ?&{(`qtrQcgjh_ng@!ShpG z3^IExuZsmj8Ui`{WNL71r1dVUy=y&}_eQdKjmuGrlLN?Qc^c>C;!7F1EB^M@$gUeh zm&Bc}b=|ucU>Eov;5EeND4}hzGVFWeAo0dTQ~_pXN$_ooY65v7(Uu4&%>CBN*-O+8 z1;yEzCsLqgA;M7Yg|z>0A{uH{!rsXl`0n5KIRHraPxP{Ml_f6qmFaae_$C$dpigBG zZs8tEnK}x9UPp87yIG*1)ljJ=(qvc2v(~Wnfuu5L|MiaN*=GTLYozWcTBliG3h80y8X=;5Rn#(r zQ*=5Kfl}pqcYS!V&;}yNp5Fsc-r#)B=_-{ANV~hq5)Og0OQCxk#SxV>(2P76GM0N6 ze4YYuB0WU;4?%QJ>!oqN`P(j$yefV}Al2Xe&GaEB%gy3B`2T|y=w^fiMjT{Mgecy? zQM}>*scjn?nNz4!?tj=!%ttyn%W=KIXDQ_4C)ItWwMX$f6JAYCw zNQr5+ctN_x#@53O&*64CfPtuluJt~1oCwhz9T|>GhZ?9BVVY0pGmOEL&U4cPC?v? zuQCT|`I=?9Cn-mdO4rJ5#l#50+er{$l{#Zy+gHCUbw)@qxFX0ColtA>7W+{4*~O7# zZqDS;VzS(`RosN%uI-4$1kw68%*M@fNR!VTj9QF+gQNJlWff7kr0Hl3m(JlL8%>dI zx%-66xZHl^g?C3bcGQKp3@gge_|_3nvzYnkM7GOI#|{vzQ7g`8Gsovnkb!r4_lXCy za52trCytM;J)*OT0Rh$z$?xs{M*mDOk(AiiIeO+XRl6acWBsPobwboX!$b*q(hB_EhX zwa9roQB_qk4QmTh`J{}dS|wX&mU`!9X!ytuwu-b5{(wnnIqaJ4?ID)n`v6{lcLr4) zO*7NEEJ5M<@3J1*wA!8C8*w$io9fshuFY__|MJ%sxp<-{&8Do+)8*ISAWoqLcC5Vx zORH*#e>&Qau`alRD8_Jm2Og2?>7bp)Fz_|O*5cV5ivc?S-)48T<}e`wGVI=n%&D#V z7{aOP_#@ob%~_LL>o4l|m6a|Mgs;=LzzzX(>!QugPjvL*H4lMSB@>xf)2FI}&f3t8JvZmk zcke8ONyqD>Q_%4siC+`!>hC$%hmD-Sv^96G!mrF}b3Y5c{Q%EF{QQiR=3a|r9!g$4 z&*$c##oL1WECQi>vp|R3_(V0CqTjwSHJY>Ls3%Ku@|XnfvkR}=@OxGHud$X>{>L&$ zC<(#V#p_eI{Id=J8|;;h8T9i7ZKxU#|vHG4Q`#I!-3ysqV>wD)T~^?nE98eKV?Mu zZK*xc_O~Z~i~l2iIv!TqHHW`er`6d4SM+t4hz+I6@scpRdtnr$PMf8g%KPzQDjXjT ziVqRKn>YKs_j^kg?Em4OmRo;9K3p2>^oSff;@)C6KaVnbdau9THGN%!BzSH52bvUP zM+94WIMZz8?Ge0Xe1G3mahJw+y>3Wzc&p4T(kb6UY}H4StA7}~oMIToR9B{R)<)xL zW>YE0w2;yh8gs|N!2eO?NtmEY(N0aiWF`vK!dOjNsh2HHlPOs`x4iF;Ka z8SY(1G;c-|^tkqRc_l5Rk0vQmH-3)BeQ%ZRF5K7Lu{1 zKQbR9a$O}Uz&}VJa(iI9Y?MVcrwP%0-_fQ~*Rozqm%np8&D1Zf0u#-WUV`jjaZA5I ziBUVX$Qa(&<$zF?Bu|R+cxc5{RF1pdES9KK?(+_8uAc9)h?LE#fwjJ0x_kHA-97N# z(XGL5Sl0c~9q#(`;b6SpDy*hhtOv0|5xoO*Q}gurvqyIiLgk(fJyF7!x2v`mM;$5O z+dngpagM^PBJirpIN+!Lw-no$k|CR=lU7%&LWBI#W*7vEA zbaqXgaQT%vIkB&=G4X{mpM)FaLu&|kUXil+p%f{AhvZ35O+5JL_@CP)bOv){qBQ-% zs~j0Z2QKz;9nQI;4f?M)8Nvrd$X@HZSQne{-x*QYLCq0Db6=5Hxthy(<`ON^PuW8T z<4(ZD5Oc=&0hCF7YNgn~Zzm%=QW2lJG5yck`6}&yE|&>%F@HAH-A6dNiYmH$8a)mI z%V5=Nw5Hx|)oyg`KX3C&*@rB(MW%QD=8g;}Pf79QC>NNgdCG;nm`rm$*!Y+3NV=SN z5#`*aXdot3cvV|USdF?NezWi?inLySS5}y7j@vOE37OmOwqaPUzwDP^O+={)m6`}w~ziqi3;M8*j zvATyGd%ryCqV3u=)a>(RKFSni-Mgrw^9DDfHq-sPEv1AE5E2F}!U-C(%~9dt1T66{ zQ|vfRo)3h)S3|LP;okj@XQ>4p1aEfuz++SXps-GksnPYna7`L568^HU#n=c%gbsGO zG4KEFO)HdH8G zm*VPtdXzisQvd1Xdh?}6XVn)PWB*RLAq{HcaYh!Q#VhA&K*kS?k5TUZ=lGuiAf^fY zBp+h^NQ#p+_7ZdKs;XS~_OX@-<~U(;ji_?Mvg&f^s^^A+Vwc;phN;KW62F~HR5Zi; z-bRNIvlN+Hno(?BY6UEzqeWeq_lOjzIak!trMmJ1-B~v-Lr(7?=)z;H%EXH4hvUF{ z(M>Pj5;`H+EwCC#4dc=@>x4(I%nda=hGiUK{*&hI;fcdY{9-&*Lv}2xs-d|77L>W7 z8+%|!Q-hxmRVo?=ZTn1|p|Vm3&A@PG6SPG@YRbwZ=c5sh-q8oU*chXNeOS68o5PV; zD3KUvF-;fg~_`PT|j+3AaiNqUB+*mJE*4v2E zEkR9^F50@$qKk%*TMP6#M$+$i*(!nN8r{m_1jfiXrN2A(*9F?eYKu0S*RcG1%KA<-kYVzCEu&@C&*i;fQNg@ze}Ykamq(TgC`gbXfR>O zV{JwyK{jSpJ(|3;vp&^drXr$szG_H%2YUwvnuurGZj@B|{Z;C<(inls?+Q1mm95|H zI@cp^KaVh-j5_Qu zS&hEQUoOTrx`iytal$+|n~|SOR~u}A8e!GWNCd$8BHH^`KOk#NnDxPZMq1RkKLOqQ zYew$=nfL@Jz@$$Y^f7TTYt-mv6BD9j+5A=D@1i28NqQ*|{+PHz7)&b+3jVeGyJkPGF$sHvdSmlS*Yg5_ zmpbVk_+XpKo#l8_PjGWqt6Fe)`yQ0Rro*xE%Oq7T(s@1ss(iUz{-p&e`}M`p(aOSldVa zmZ)`RUoE~J4Y~Ip^j5B;b;1}uP=^cgX%3Q2HS0EKj?&SZq~L-@&(5JoQuoB^{icG# z2*Drfw)Yx4ex0yNV#wHo#b5XE?KShVjJPx(Y!-{4Fy*(CW5R*9CcEvxa*`OsH5*xy z;{2}fo+-dip*&{czwm-()fTGENz_u4_sF(}#?un+2$%kHh^N=X6raK(T1V~_)$9m* z{`3f5*2Zid<|wMqUVy;wkSuVBC7c$t9W?T^`(+-OZzluRoiPXX=L1WN7qW0;&ktV< zzL5!ngwooz4DIRigXysNaChv<($(4OcM7asa0(tPzO`15S*p)zDo(ULQ$PbHH2us& ze(|)+>1tcUwZ8Bhk+9P0Oj!7^UhRaGE+l+2G-D#@yL))>b4Gg!FE8iu*UQb?f9dFv z|Hj}dT9CbTDO$!Q!!+B?Qt921D{8}`F{EKit=ZWB*!Fix4rSd;6{}(llF$5f})k+=Ko-Uv;lm?ny|MsMs-Jlo8z5tQR z`OURSSgfTRah|{DPIceKQKHI)5e|CLi=GN~T3IZ`xsFAFH4M!e3RAHRtRo zt+twhm9!Ja?gf4DD@Tqol*U20ve5RLt(4tZ1O(W3e?2ImoIWh()o1LjLR5MBlC=%y zbcJ1#*}?1S38@j~>o{|DJA!1U^Z9uV1)lU^CV}4lh|E+DwD=3kt=sfrlh>1Gj`%Xt zi&NS5-{Q_axc{vwcKB}9;WXYhyrA@gN5oEBYrLCkM2MPXm)QLs6`mTVgh3-{TNb#}R3vx(q|M@@&*pzMEI}$L#XK=A? zWjDwpXn5hE%eIx*EGZEp^?HMprs@wXMtvKZ!fH*B-J zEogZrQ8!+ny{@q$B6IE&O~!>2iZj3^>-+NxHGPryowByjHM5qrzkg-X&E~iKqc)JH zx;n9as8_CWxw{%>2h4Av|GuXRP-W2EU8ejObliG&d7SsPchI-5M!eOnE7YC8mdkSZ zmNF%IeNGLM-CkJo9VA*V?R&fTv?ymGMe;6KnSMHyeRa97860u-HY7{BpeC~0I90z# z#{J-CWB=$@lcwz6<<(bo9xYP3Y~yRqv+kaJ>BH5 zF)b!41z@(|eceOP5w+44l8N5G+4w+@V&|@smcYojMT6!S^5d99830f1;PNHD?njRk zA1ibe>uK^`{OvBv6%tWZ94ip9aC}Z1&tqx_TYktq_h!-*woa(|JG0C{hHeu`xS{`` zD(9>U-6dDnS{5MDvNKN!5Rrxe+T1qlhQ^&^`?@VO7|Fx(VIvFZ=DDXEKXEy z`1oC&e%zSQmoBHT`7*1*8ro#gOIKQ;9I0JJWO@11EFNddECr{@5S^*MkQJ3h&C>zY z=vO#Yxj*rUwc8 z_&`oc3LaDOAlFc|)ic-6txxsi2Zm|Ff$UXK|G*~Z?lpIi#J2X2e7tlI!q<(f=^bBaO{B-ylW7IQpozO$mr@=it`&F~8Fzac! zwTc<+>!8H~ly?q%deTO}es`7Jjjih)>sR8(C~nu~y{~0T8{c>D4)-s{&z4BYYooE{ z{S96+w4TtzVD>}mLE4R36{^S}(Hj@u{dZVX8YlKw*=)&Y#eGc0JHO|KhI+Nh7;*~r zhD`dR`4gS^^ty)!QGk7rliiO7Y>vaUaMe$L^s9b-9I3TBop^#ftSl)~HJ)KNmUZTZ z2VHzJ?F9;D+)Ujz65T$Ip;pIiB6#Sn9sBmh$D%lRc`mW^PV{o7UO3a}j;V=Gt63Eb zIo&(p|L&>*I%wl9bYf`*^2f_!f_E||2I(_UK@^5{CVK-LREGhR$oD?*P z+B3wa9v(0q{)HQp#pg(z&$$RVh;EETvnhssvqmBHM3*l*z(}nnr}c;b2&g?lUzHEj zTo0kXpFKwQTdudFV=Ykt2O}3pO;4S+s`kV_{Vb7XF*Esu34|?ThQhVSxV>3RL|7jm zJv42P_T=I1UBamtxDLM?O6TF$p=|r>0QiSMY2zp1TxaP0Qk~9`UL5N6c7%Vo7hNHo z=PiHlz^^X%F+x&llE;p~|Mb-4(-QQHQ?|?p8c7xrcX1B#cYy=dP5MXn&aas$W+c=7 zA!^r^_2%I=sW+moOpm@$f}5FNt_B=b-`_Z=T74r1^PcU_vf+XpLf>NM8%`euWB-q) zuMDe#Yr3XE5Ku{Jkd$sDr9ry8OS-$eK|rKKy1ToPmImqW?tVA-^L_sG(sN+P%$l{< z%nl*JhI#*jGDS}rrcP+`Hx$$*B!D*kII~pV4ILZQch{FnyarNtidkIbD{XJlc&unA zdHNBi#OampkQ=?l?M@k;(jn;VXaZwCzwbeliZR&-E`j{U${F-(}98QN=Eq3kn?4|5%(2l;jhs%b| zhl`>R#MAG!Y6Z*s{VPjiwF5zN6bySWY_h6G+gsFdOwNfoZ$Te9)5Z0oJ9 z4ljL~q=!GH{|r|wp9+OpoE>95f~qpVGDqt8vgJM$4}H)UXXi?4+O zs*{P+XGP%~HX+(viFi>p7%qs_16K*?QUb_hhntfoNm+R>RzPa#o2{&}QH+2#8sf;F z1JKs#aq^YU%beMdU(XDy-x#odSrCX}%5&wg20NII7|0ef^d|Baf2pb)!Dxu(Mk{QY zM;p-j$PVXxL0mo^ocK%R;DsXWn@1gOoQX;S!3kDhV8w3VT1Zw$3kn@{iG#2Ld5o$dSiJh&Bc16|#oDxB#0B zos6BE3b~;&=TMBcM#}!%J}+L`4vF?W-2`+e6D9pPqx{ksrP%qO>LM>TwTrJ{+_oSy zS-UeGpDFVh=o;lEoLz~#5Zdi-2+h@>RTJbTLF@qRa|jAn90TF3f;{ip-pD7g@Mwoy zcJf~Jvz`t9IAHP*8d3<-&2denx;ffQWVB3PL*F4~%pSMSB4;camp%4}z2bqR@11jv zf@!^@CG~6uafSf4kv`h12b=kWns_}hejp;`e8XD>+4PK2$6^cw-JBxzewcGm?zlAK zs1JwWZ}`pWmVNv<(Dx~qo2gYMu4L|?2!SJR)K7=|)~Lh1Xz6!01qIar zBQ&eE^1GSh>sSowOO```%6gKH2-%WJWxV6Qn@lp~4QUg;j=Y+(Y8^W&kUsX`$CUnp ze{5;@*-<9Yx5=SD(ISkNqmNZs?x<>Qj0i)~wJ2ApR&4U{=4VE;<%dvdjiQR&q^TM@ zNF&1nk;L`jA2D}>As^GK=@fIew^-bvf`(TU#d&!Kikx*kSjl0)80Yu?Y?c#^hCpQ+ z+-F!Y1m((WPNmSOPMqiaIVAl9YmXAB7~hMQ<9BSImjxt(r|GI4R8Xu$c8|N)%Q8E;FuPu~bUvt;+#uf2A{Mz= z%WAT27yAVWDT8ph7+1<=5%eaSC)@r8fQHdTCL#JeGPYDWeK8$nfl0AxGdV{dNc&LQ%tbCz&7S`uTY9sK zc&*{%)hJPZ`=?_4+98j&qXvlLVt&J!4jbc3RKZxow{DecL4_@&UG(rs9~VawI%C=_ z+kybHL%}L+i;wX-zIDfLwDdqHW5rBQoKAQt6*sc9W4zJ)8?M2-B;2Z`545qM+ErvX z^1FNM>|1?zOoe;6`ddzIHOEAdqCX+*hxI>>^VHyqAoV>r0s4Xotm{6llb6)z&3`eL zvr?tfpErN!h6dahv)KLUS3)nOe5?p}ccOd+_@gHtyByEkzP) zM9k*lpl-4eKgN_Cjs%&biM#w!`T;}+G3OWy1_y+H{%U26v?`|2dO7SjU7dZ>yMDYQ|E zyOleX_qX<=$??}x({EsP)xq4uuiCk9)a0<=Ew>5v6q_qB&XWRVrG!(l=TVNQ!Q1TZ zjZEa;lr3Mg5otRi-EW-&m15{fehNFKY&W`QQm$Wb91+9-25hLA&@!kUvJj`vRr!%$ zjoH~PJhl#8_Cvk`#;Ax~w7p4K$Zvr@qlP}4=xQNyp?H&DAF=8$wFk5r2kn_pK+6gS znZx$>iS=|sN5O*e!z~m7KP{m;Ov@V@*eEUZwyzjPJPV=24u|D}R|B5&m8}$~$nPKy z`L7mh(}ySqLFFxxfVv94L6e!JYH2H%i~O3Txdk#@%V{5@t|tpO_*JWWCE?%BiL#^Y zq#>J19^pz_>=q7*)nlQp25e0s_Xczj@2>nf`j+)uWpXKD`3I zf}z|`cvMBX4SmBvpQjyVPyq7$`jTbh(TA5NQk0Y&hA(Ul({v*md<(r%5x~*}fSf>n z^A}cW)RUK(QFC*J7{fp{e}NQqjSNTVFrq`qAm_E;dQlmzJ_(;}n%;_8ahF3D`R>TL zl%R;g=0Ur5(5Dyq)rDJ{8WDA<)JJlb zlTt|Q)7&fkWirqLuM~lCOuMJgNXFMj*O@j@JX*=$_iKWt=?wn9u|y&7M{g45Umd)) z;^s5?TJ7n@BP*8H8|Ale-*5|aHiPyhQRPVW{BMl1d_Js!$s6{_NRsj@U$g2+6XO>n z%Pd5EK8V_{i0{TJvC({7ze+Hzeez`?>OOn1_W2UElL)1`Gxz-E)WRKLv_>$h>_{&q zJ8xQvzG^qZ@EX<;C z87(`Te39#rCHg&H_vS03O-)X+<^wNO*l!w;SKf0>$HWH~^Yb2b$%PILPVL9fMI z(cM>rgOiUSqxxrm^PX=PnMTwR*+58($p{xhf9DLstd#*d!q6% zaPLhF)f7QSXW{J3_3u`zp@L4MWN6CgOD}^f!kO}uPov~${@}Uz_R(gn!8lqcP4Umc zK@<}YU4UrbjqM*Ry!LSnVPeMeWFq`+q#TGi z?eta3{R_^qZDQbnsw|f~Xu*kAu=l-HCP;|>2VoOo6=k_qApGJsbvRdfgkwVdG1pO% zZ4P^8X;v*OMoC%5P7gWm9;TLq@e%N_fF9smjBFw|!oR}g3bT`p>i3E*FJ7Lnbt5Xr zk*!v5uBLtuqaJ@~3JhXXzff3fbPp}I#*qvfKl6SdbcW`&g7a!}##=cW1)jIjA0f&| z!ck`(><^W5Mpc6cNvsSdYSkU#?Ku@3#PHu6lZgII?(RCs1D?#N);Rrn@12v{TA)sB zql>I+b2-0YHWETde}SWRdD>~cX@}mFQQxmQ*q%%$>22uQ%$ZQC4!G5CQ=C;PJ{dI% zp4XLJ#eN5T(qF%>)}8Tyh))wZO>W#;`_U&+SBCuhO;;vbqrE%}-TlTn9WAWsg@{nB znzD>|X<$BGRCZBk*Z}$a?a4cm2PvpIsF!mP~zCqLY_pb8D%_o<&wbX7&v#&P|F5l2x#FU?fRtY?SW)aam$ zk6_djCfH9bU(YBXne1@G`00zqu>pr0=MCVS$(O7*^R~i>Es=((&x=3%bIA*IFyCo9 zy#(UM%%GoLI57NQ(O283EQg>P!Avgu(0_+^l8WlF80oDnQ3oQ9(g@R;Xm_{U@1^QK zUXh^b`_&)`ydG8c?SuA6{ViW8@~byi;}_>A%=)gI3s0cFWz6=b1Vd#iPd?12DD*N{ zKQPkL{TvE*+PKSzi^2F)%u;!4oh?pRq6bnACakE0IW70?2w?7qacAH19Mrl*>D7sQ zH1Z(Hs6eZrMjuuFFm04`g zG*UqEdIv%a;WA6A9>s0#$S&dF?;T^dj|DTN#c+*CzwixZGz%13y#a@KAK=2sJsAC- zN2A=*1yJH|K4MT(wzRRuzi6>GjLcFEA!b;Q0q;T=KAQX5hEq#kX;WvPx0gicbf!V) za9h5T<#Vo%ylN8{mK=l{X#V+DjWYiCI}#r%m;vTfLdpGN&m==DvtDW*WGDA&Wj?#N z)?$p(#7z@HkJsw8AO%|l9+db#{gwOAP#`O+43y&U{X#yA9(|PuO2F#JX{(nXQz9(# z6guZ?UzGUjy~?Ei)1yadZgmY~*(>B#pR)0=TKA>ql~4x(1iqL$Cl!@d?z!(LH^+(u zYw|QbKw0`K<%7^LPCuMdYHGwXM~a@=vOEa*+}kVPH~OC1_N7smv=9uOkc)qolM^}C3=wq&;N)AsC;=E8 z;#V}{)Wn0Gk&Yis>R(@+p3*ODiWMIu!UgK=277sW6b!{`wnl7m#l!`%?uwZbH)Hi9 zCM9Gxi`c`mqAC4gu~Mxri?{|O51DV~w1z)tfQpKl zM)a5YuRoB}*LSQsMhZ55+49I7e0h6qx3zTFT@x-Ym>qYCdZX8mreInzpW;9%a^HOM zw+8#y3H|D^cq{NiZTaJ_-|1Ns%tq}lAH$f(b(>5~6P+JF>S?~ijgUr9oTEU<*6tbl z-G8;w=HbPq8Zb|H(Sr(q_k3J=)V2*)x#Qm^$z@hZxVGW8517dCDonfD;*FJZ^mLfa z{-ypChj9~mav5+scq=Ay^|qq`OU=F@B)b>)U^^BOt`O^W4m{YzQ z!kO*agDF*32C=*;B1Nv>Tm^Y8&N68@{6wT8L7mcUDm>!Evt=kB6w}P088H*h<+%z{ z%4!rik~R67xPZXd=p;l6ShB9!?mto+S*K2{t9wNzYe5dYE9oQ2!4!4oVji!Kj8|_G zxW|i|f5}pqS^VPR5vdB8&dMd=->r0yed%6`SK`lj_bR;r#1sb%m>^aDd-wad?e+SG zRY&l)&b717-;`#04((aiFKmgxrH$`4dc&S)P&qV5ngobr$s?@wx4&@E_K(7d5CEgz z#WlyEsBR8+oic0~sKd+mJdxq>fwm``8|98?qj-j}=f#phLINYmM-P1Pnbq3$B++fx zmcc*{|0Y({J|GOJxn}wxJp{8AA02&0V$UI_E;8t-tFbdi`R*#vc6&YkN*9BQYOH8W z0bFVh3ebqok?{77wSC45;Gg#eh4&%0HwO9W_Gb;9E;oB^J*t_5;S-MgmC85rANsyP z*S#9NzcCr7^gO421_l@hkV0^<`$|NFTY(4s*YcOVd9N}!tvJjxpwM>oP052XV}P5~ z*pbk{qJj)^$kKk9iEu<-d?$!6QL!U5DhK2b{L(|6j zrl=Mm}=$oHJ(MD(vaa6m-ZLiDrcb&?uEqlf4Lj!ySIj3_WfB zc_wk9-XN~K_su+T;K3Ga3A_Wdcx`9jBp#XZXlz&=vzHNc8DJ%YTVz^4zH0cxsCEiQ zF~P^6J%i?@%>$x7BAldWXnL(J>o+XGOA!y4C!ZQCf*qhL}53YuU+G_{-D zCZPI8p0!OXnVrAG{3pLSN=EUd=epUb6Ix|pM;2>4_pvl+CvkA1%~oTS!m{oF6w@2JxZr$^a9?xAR? zz>kO{;iE?Ovc5?d^+DnH3PyKb%9G*flS^|u=Kb5%An?dZdaqJ=xSzqT3e01~yr?Wfv+ zb{*^mp^E}CaN?;-s~M=s#n9ZQ|K5hba_gxQ89+_-EBK1~s#US6Su*`gQ(Al5$JsUe zW?qpaIYXI%W<8DVdMQR*8t{H!1iRk#<|RD?$%@Ny5zX}`n&s6fkvZd&R@B5C$p>$V zzl*opdUv+SN|l^Yj@{F+?5pJ##WRob*24)IIzy{F{qP%vmkd>>1rWm#ftNA8uBIi6 z@^GMxv_9+iWb~3v15BJ0Fs9s@iLzy4KIz={foEV^(%rF6Hoj`J0&V?=oI1cOWOa8Q zAQ5WbJ+lFqC;iw-{kZ|`Cj>EPE<*#h16siV;oO0E zVkOO7#HozV(Qs@dIlRr12DVIWc;_Fg^XX~*L*wa{RQ{tUa3pnFC{WBbGf~$d9pQUN7r>+HR*6HrUUv}qhOysuWsU3sLn?ceX%VlEwn=CI$m(!b+S{>m z$?cT1MhKc_cN!3R@VzYf;|K2Cm0h8oy&6;6Bct;w1|zhTZ;y0|Wwc7taaH{1$}lF^ zvebc&yL-K*WQLUx)MpC3HO8%tNwMlkK!hyuc9;;4qyo}Rmed|lH0mRxk7cz?TYE?S zR}TBh3*)*%J^irp_J+#x^BnhBfu(Z`5II%M*{Qf9H{T7`Ro13dC8$e9W8>qh)Hq{; z^LlM&RoqW+80-dCPbbgswtlkf)=B)E$OoYy^)ukj0I(E*2ok+J1NH`~3raonhfr(n6$P?@u<88(&nA}TLZ=v3V>5>oT!i~7k_mCpxEgyPht z8?pR)0S`^DlHlQ3>1J0$UF|d-?uX8?P*?!|T#cPlo%Ft^&VmNbq8t)nXFTLz%V$xA z0EPaaQWoL?L|7&A&p0JVnA`QeFEe;+Lq}=|em*6Cg??pC(|<|xk)tOW0Pw1a(TSw0 zO9hd)eH+ zEC?2nYZf^>AzQ7OtS&F!c44P^>LftzDRqku=kkVsdN1$o;%x2+_z96I`=}8i9R;=&^{c7;Ch>?Sq-3V=41R_FVQ9c?qf_#!o~< zoIQHpK=Yg?$MuTpngzsl{*k=KZ38YR>AS+;w!EiTQFz+-tgt>MRrhoY(ZG?uq!tgj zd7`-omx`?uJww2O0SvnVh;kT5+2RV;VK#AOD_NyyEU1=yF|9KwY&RM z|DfhsfDKxY@7F?)jOVxn0?N7MAPEeAPH$w*+ScS;|AaHpTD!1R15FKJBII-PJ_A5d zEz_R$`3VMN z_NYt=7)BK0Uj+`h_Y;&v4}f_99C6`zjhlzD4mzynC5f}t{`6XZExX#n;h*JZTt~dY za$d4d?2Ze2xYOI4P$78Nx`Plq@?Et3KsgFO>1iDEaB9#lwUn-jQz9SC^aF>YUv2Um zCLv+@;c~0SgU~2MhQ)yHz^JAb4sP#N=@j?R8TC_pK2}x(oSktW5(IajwViW!j*Px6 z;M+i@Uy4?Wb+ugnfl@r5@u$N?MZvso!)mH>H)t&)`VDvfX!m-6Mf$^+B(RrljRp>2 z;^ojj4JacS3Q|s}bk=#afR`e>^D|?v^{Gx%%A+Q3c#W>4pdhHRYbtkhZtdLJ=*z$9 ziRI8|EOJ9(wH`+h=*Xd?2cp1Z0Rzda>H<6>cnQ@5!I{9OEUyRwXBK|y^3w%v&Yiwt@F8Fq&? zv7BWd-nbx=P_Reu{&*ZK@)rhe0KFD*uBJwI34WCzO_8c~8ph2fYv*af;7|ygo6E*@ zz!81qfZ?9owZ4H4#$R|@_;*8R^KK6HyMiP#gtnG@z@{G#AUr_%)o02z3Ls5iYfJiB zd5HSI(NikSBm^=GXm9ZqCX0 z@oydyj`V$yTQyxS3_9o3-JFsak7`KoxM{7vw_Y&M;V3%r{l7|60N=RUm_=+uW!f%Z z>^eWFc{jj7`bJyfjDnn%X!#+5c5x7dVj=#cu*c&v#u3gB6n!w~XWMVlb!R%FFa~Z= zZ`MHIla~b#bB>k48d!fy-a;0@%KIR!I;|Rs62Zx4rFAJtNQ1!d zQAm!)*JA6^%xh}G9F`?JuiHI4;zNnJXwOftFW6$k7y^__PRssQHz88$Ypl#no2T7l zlO@+i>oaZ8c`%>)s_a_RaU(UAj6#w4(&M4=!m7fw?A4r zNDB`SCd`yYDxD#K39_JMmQU&cX~Cm&lG~}jQ)(XkVJXNdAxOl;zmj~Gh5=m+;u$p& zq6H?=x8FyL))N)l9Ph-H9QB6y}iCf!V-Z{o^P1d*{Z3w;hwh zCxvW)qeQF{2<9Z^TS^`P00j&H zX)lgCeMUZu^c#i)V3>gin%mVzefZ0yZK3TotU-DQ(<*UhUu8QV0}eK%$3bG?X9{ks z7K5*Eo!%A%`~DhkJhpk1RaY_G)#&pV>*ZKMEDV-Y-O6jpQsjo8>W{k~7oIq`GBqO<36?*RudPsWf zX!HeIuot*wn|GC@mDs#K|3EP`&%azGrdv!QJh5!r+*!*qc`}HjEUbLDX)08X)=XLp zG+;bn$M2*o6sSCMPaZl`e(|k(}G+6n_?#X(i4yLz=d)A>?a}sq<}7E>Db=f zw)hGTh2CSX@HS~3#9mj-k%2Z@v8vC%G%TwezhEO>I;_PY8PtZiI%e&9usvhXLP$u@ zIT6}?GGiXk{+i3i$jxpuejweX*gcXd2q7d#J7*oOgMul)q}xqL-SQx+-rP9{C_|tP z16~GQIjLd2)e;b5Sd;4lHq5*4U|Dgui)LAHSvd(K-gNXw&F`5<*3pa74zEC5LPoIA zPuzSxnkaF6^ddfOaVp{pB0`8ba@?;X1NtT~8-or*p?9MeVUO9k!Cc6GGD>bGaptZ`^cUaHK9HvPB;sMjSMgc|Lm7!8TL#h10nm7J`axrD{iy_ zcN4lx)_C2G4;J1-J46fOVv*F_F~Tx}_o35taz<6Q4*|PQH-xj)KiC~b$3qbl-XfY` zJ6B6}6`-ZCEQ9dz+DQlh>#$otq4D8>Cx@Faj=k*TplAv+u< ze8OeTM{y34Se~B*b#tAP$LPVE0v?j@$Q7(BCqHGHioCS)P29Fm zi-w#!8f-nGo!YXqBv%xwF#vt!K;VfdA`QoRge}yS(1L=hJy|rb-);qcBxu(IwXg1P z6X(kntp&9Wj6TH2g5Elu{P)eIuT&<$WUf}y-oTN@zF<3GXYoC1)u?s0|HKVc7nL+RP-v;Kx(+Y&$Z z@XCdo7a3!wIHLOo=B=&Ct4j!4DH(E_36aWigS@%g>Hu7)#k}{f`GThAd+tWPz&x1v zWz}VyreiYjraXG5d*tIV=>E(do>@Np2AZ3HV7S~w*U-TmfHAxzl|G<|n~geL*3U-s zp`rGuA@hIyhW09i%i8<*?eS~$@Pe734FLdKkz!1p{+Z~(yh$R!5~!%BhD+-ZR4^F5 zH6JdvSgkxkySvhT&+gHJre@`SWwKX>XZ7O24!l2{o+Zel->~l=ap*J}0&%L3N*-E@ zKu84S9dyNr!_tfyL>X=5XBuzZaFM%YWYS5HL$3T~!Cg_!>Vi%jJ&X9q_#B?R z#DF}#9e#G!@*r#_Kd4*4 zjLUWg>mr;IscToqqxYcE_~LQU5PY%IJvL|-vmFm__~;0(QU9oW`;G95i+CV z9ra;*BdCP(KO1IaEobw>2s!STB0_^-x&!p>cWkrEpb)SK+s!D%EO+m(C=ny z!~~4il6C6J_%!;GQTZ32*V$O4nzBur68@?S5@Bl8r5JXC8hEk z6a5%|55}2UUUQ!z(0U^{W7Ml#C;NfBx9aR{U{fhE*}?cT7+Yg){rjJxAO)g@yFTJ_ zSr9qeJcYL;$>)wVBj@PsmeH^r$~m$mAcjPHXNUncpAL>SB$b_e;;f~hK8>WFOKs*q zIu#pSHef^)HnXL*4-%?rJjqZ(z}epDd$lL<<|Y=4I#^#g{+vm!6x-J&a@3Q>#=!sT zRr?V=@cI2R#Z^aV+L|mCi-+KFaB$L0EbS_rJXB4# zzT4vafAWN!=6Jl&5S`Gitv(Z@N-w*o6JG*~g-R|XX`oc0kxTPOh6N)K4ghCo!cb@P z%jvOvHKSk*a_wTklGV;sTB1H8XxWl;G@4BiE4|Or{(}=_g>E7Y{$isCU(V zYL1gv6$G7DSab(tNYruDZx{vQ`n5PYQoGF1T;s_JQZciT4{jv*p+$GrY_M$a)& z+|w^PcOm*!h^mmgibc9)(w_TxzA#wYnELv&QQQp^X@4|oC1INA6e3fsacW&XskJXIa+e{P@G=sKO0LUa~DvJ z{Ypgh-tSOiPN!75&j5JO;`_)-_`3 z^ycH+zehXexE;7dPI1_{qq&|@GT-eu-dYisibMGl>28na<>e)tnhsJe$8x{y8Eb2` zKu-pw1W}yL2U%1h4Z7U#w`uZCeKTM&nbyvu|C3YGCHhSOJ>%)Vi=1|{PEc6$Y^V39 zs|Pk5&C>`r?;uA<=4k21nbK$96Hj}l#Cp!~PAz>`=Rwyi^%f>d9Q1B6_#l`I6Il)P z)UY9*nPh!O1g~Z7%9MKLrL`6YgzpWAClp z9KWD+ujZ|#-5p`HraV@sEyREl;VI~)(Yn*z6;w1@61XqWS%wtzh__N=Ha1mp$ zC8<-9j#xg>O<1xq(RL)mMbpXfR#V#F)SlUeo+sS4bv?=TqR{(b)(F4XM4jhl$Qkci zWtG1i#gQ=mY(2|zSR*aaR6Try*U^zLO$@OwC%4gE6LpYV+k<@3UT*LvQcLNHtC#5| z3TZAwrwdhnJ-J0PNbj_{_~DGJS*_{hbB+$!Jy5pLAyEvjjYt-g8nx$E)d$WKL= zfj@&3NA*|-0kOu^2V#tOy%?9`5vDbS%z9Q7zv(DeYfmy7>zfLOyIZE!AZV6jC1zq` z73e-nWB>S*TGNWhtv=Yj;STH2DiYXO@)i=VCx8l1mVumB-moCN-)rtBV(eg^H#z+% zd+ggsoqN;IW8QU1gbvXLvJh9ifz4@&i5zc>351i2S=}!h&*F`IIxVrt?ZWRozE=yRUV^heBN$i{{ifJS?tm?Z*u&$dAhTeBDm(U#Ggsm1 zeIj>Nu{0a30g11vke$Y|xnHkAy&+Z=-2o-mjd;Oq#0bHg@s`Ut#R;b^+l`7*PT2{I z+@rzn17`4lRcrQSvtbP&mNv3?3B0#|!{?b+IV|Xbow~6m8~_KJv|sqchs`)!O=07>X9UCEx4C_HKk?w49^SMYFExpF(dEK3-G>;>g{R3NR(MpC<&SH#*V>ztqa2DQ)V=3+w)9T3 zAu*YM&L*R&orQXIIr3GIFOq64fTwyhe!2gyyOd81CDCq7y~_WYnRlZlzy13Z;V3a3 z#Wl_%9`yy2{Ta%0itFk_KcBX{&jg~mX|%J-(UaH1Zu(h3a~emQNbOy0u5ptjRX!!% zjZIAhRPY~Z-bHo{!{t2J&m3zx>JQI{h^U*GTbKJ?8rJW(JR~SsDVc%$MlP}`BbQByWZAzGi0#6t0AMQrMpr=b>UH;F1 ztOj$j)M0k+ID&^gU3u+T!8j?*kFhX&F63Qa)IsMVhWqVVMGhw|33ddxHX*%NExwO% z3Q8qUeu#_vS&#S1m#{M1_qEBU(}^CuaVt+IpFX-@xNe3mtBXqJylG4WFYG)(UE|T^ znKz4t4RT9*x+4c8O1Q2C`R0(Oda>QO@2L%IR{4X??(QE8+H=s_F1?Ql0 zk+lroITAdFVMMm2jcGMZPPTR_VbG9@a_${; zL3y-@<*olaKI7Sjopp38yqTm#87k8I_F@C8#<}??%3vU zE2bKI8O~fxHW`K?)=#^Kz~_;xIYnknK`m*4?9`fY#H|sHpo5&(fI9A*O*VY{9ePWf z5Crdm)b~0&%Z0S_fgps3BG^_@oXnZ}S2EOJ1T4lyOYe5CU|MdhFTc4Ai8edkIlGhm zb;2#_;h^XxLQr_Fv`SNCZG$;r)94N-;$`vc}#qOW!z44tsdT5 zHBz04Vzg;1t!bb6!J-ezsjnGXxnWw82sE_lxWDZtVj~G?tWWD_*RaQ4sfU&pU81jy zJc#dT(0*g`bm8hrPVGdHm$N8QFw}YPDQb=p!5XBEua98M$*=^TM^2Syi!naz82=!U zitzKn+WRCy{7*l89dBUA9j)h;&6oNu9*Z+mTmoRCu;+v-4~p}xV+ zcJG7tM5KZ>n6SX-Ru^gP4_+|+p`bdmd9rhn#C<*PrhGKG5i{hzVbjrlF%vVvo6NVu zQ6Q&4IHK9&&*VP7m?G-5)p^$XsNG)LwN!&R>tG+VZSkD^v{KKiW5tcm&^gx!4XgRI zE{_+~8AxT@ayhApUt&fn6kmOO7V62-?#|VBbI>8xox;0!b&enG3NS__JYv%Qu`@Tf zHGVS+R<(-+U551^tEro02BH|*1b>DEe@32o(Q}qqAK?x-T^@$oK?7&Vl*6O3nTi)W zUHl3-vEr&$shQ( z8!X%%z$!h0^)@SvezISY zD?7{(D_H2nLF!m=xgN6cXJ31FjlqD zg@XsP!TYyOXujjuPu@^ERM<$|gk|&n*+@)hw~}D<&+>8Mi{#BJ^!xRA)tfVl;T^fj zUa}WHx?nYTElO*@+%e!cF#k3BW@>vLK6H1L%KC~6UknL|hK~%pe0nldX)5U312Tp+ zM=vt0wwn?XSQ7-NFtA}tAmn}IuAj<%lh20}J4{r0%oK_&WC}iP;@7wW*QfQn&TP!X|*=2k3V zw#pox(UJFt{Fz5-(wT5Ax4ce4e$8khWv|3zGfVyCVW8=WW+A(hjv*Lm}`iwLn0iA&Cp|D^f!e{zc(vd@##+Iw4+#)=k8Z zFoMRfaO>xky%|bfhX zI9ILqOq9i^l{N-!Lj*Ya{)M`d$;Is+m60k(x+OJT{hkSzCD*QL3nCS_zLlHkzhYwF zJ+}X~B3w#a5G5Q7zPSss;MK^GvJFgl*fBnxelqY|Gr;aJS2gI>E~t7EEb+Yyub@*4 zve_qk5-TCb3cP-j@aaG5$ApNh>`Rk^+dfDk>9mj>yRBwp<{~3bPGUzT`$U~#u3(;# zH?mRdb}CsSF%A%Ea;1DUR)(qPxWs2^zF%2Vh6t7hT4pvww%5iL4|fmuG*E@>JloNPA)?|o4>q#ERjfQ2mbI`@YTE-1DCK# zH1o+r{u^UkRc-i+RJDp3ES9Zk1}^&gI=?K2wi5VczttssMZyJ4O(`z3{r$9Get-T6Z&y?*N!jj7XE_*d@LvsRzf?$zIJ#QYwNq^SUBGcAI-|`P z*(Vy&G3LvLypp~>l9gWx?S#cQQ?@Jttwncnnb(aUY^Nc&*BR2%WvG=fFT;)9ykR6G zdH$s(I~bDRo_TXA<7%>%u6{Jxri7jN?$~LfQA+5q=eEoYf$pvX(%s!bG3AAe;|CUK zfKAkr;_4D=)$R@lX}6u7=#xTNbivodR-%EvZORt^iMdGQUple~BCxNVhmmeZL? zc6l!@VGjnVXbkS6y1}Ao>^$9UV_XcePq>_~;1-GB+-x|egI1}*+~oK z1|4e}{7{uox=p%F4p3vYWR0%`0DLr6>${BD0m<1Wry+Hm3OU90@_C=8ZP6iwDLUGH zWklCmn~@Adn;^Mf8l-5S-G6kk)`U1i~k8R zGTvYi5X$`?6`@uEx#9Rs?r?yboS6J)og6VIKSqSO1Z#o)#-`u#6ek`qE`E}TiZ&dJ z(eGN42Dn+4EF9)XA_F_4-ZAEdD*!=s`)RV}o}RpM0O&vfrjuLm7QeW&T4o8{_KyWkuzmiy*+6-{ld$T5J*_Q5Ls_c3h@_*SzD5S_73v8` z`^*W}w$ntrLdj=sunrrAP3hA0PBDmOQ5x$PYSj7I1Zts71-b`*ff{j~*Q}wEDLUSb|8S=A>Ffij$Im zLlMzz1yI5PooO0q$4={ZIG}`wEE#IrcyP=#uyCn;xU?V~DfsCG>Kza?1$`32;< zA&;Szp~t^+DxWX?FV%K`8+2!)IAveeFKMwWu8@!2E%z70U%W4OU?Zd zR!E4C9(DwnsS<`Tp<7Z^243)iJ;h@{bU~zq&C|Q`P?~;U;HE`}gk4sIS(wr;gVUwc zHuvpCx)j@0dV$$HDGkL-iA=8{B!neemj=;=umPU3B4Y&(8}e=Mw~myE_=bAkyg7D| zI2~Aoigst{VzI2S3&P&LH{F)5M+jL!=`n`BIJ8u|_C!;CbL$f~S%1=<3?W+>*ILS1 zu1j`~_W>*4O7Z>s_i_x%0}$HXIMmky@kfME28Rz+UlDBV^h=b!qGqN%-A1ZH-wNlT z02KUmNu#aP6gLspL;=0*P~js5kE9qw;^oeDx8*AWTQ{ys#Ey=-*R4y#w8K_@zBWBuz70MFVC6&NbziJ@^( z(1pz*ux~TQy{}Dtq5%nt6hSDU;kNs#HbW{&M>A^HL?3(AiBt9YltU>iBts~u>Gr&B z97II&FLd89ND%vk)UzJwc@nbZQLPgE7evg*Ro;6eq1sM-B38#BcHEZ52w_15DeiVi z%HMVE-nS>9(ZBQ-c_7%m$&;{KUEL(ovsu$5Ozf(KH;$g&s9LYxSnnaltxt&b9SbR; zmDGcBp6pRa!!5V zJ%;2;^h3K?TOLiiSevOS51HccTlNSWYSr!9_7^UC_sT};ZH;mRs-~Aks=dt`M2$@~ z>ZEpKzWUZA>E+7vUy4UsU(!+8VW|m^5m(JiSS)In>L=1V)Js@VHD)VT(20=66wKI6 z3&HZHL{+YVK(aLmiLXfPl{55{g!NX}5fjz>$D0n%gq&N?P=xHkZ{8w9h1Wrw-8`;3 zJ_$Y)hdX?bkC3;ntPgGaD)X#%=wmg=rz+W??m|N&`)?q;RDKBojXigM*~oY^2Dpe8?@? z*x%2Cm3#a2q|jVLUMq1h$-C1i!~P#S{7up}AKQKF#qVyqCV6LrC1=mOn0yVp>%*G& zcGavz(Taq2V&+f)EVNJn$9#%Pi7t)L_u)h_BxgRS$j3-at#M>N2nNvve-D0eiLkYF{?CtS}K zY;16b^5?8q4uqL2ANTo@oNShto4W_H2%w;=$f+}=E7y8d?&1%wz=$CeWRQfx6G4tP#j3vSszfQC{eCV9OEJu9&rSz;)EL*YqC z>{96z!a_nqK%?UO_c7b+BSy^)H%qJ*V{%bL|3Jk7!jvfswe$Ab6h#VU>FN2>vInLV zZt1r#&{q+mAt7SfwwxtolE~1SD1sRBNc$gOKSd<&UoNYR)^x(j^|t*1xV<5MjNo(5 z>doc3Y^BU707w7RwI!e_wdm(0_=*^an?rB*@uxMJ#LIt(+}atRg@pXNx{&AJrk;KA zCwNJ{dWbF(01+RCVv@!6?%G-AKy@rUvzak8EJK{y2L71p7+R;%_SlzWzJA zuOy$E>${Iwrkp_W_r?kk;J)IOMF{VKHHSn{@l9?<|%7t$AS(d;{t(asx|q$h%!*MnXj+ZJxNE2}W2b)UU)bmO_nhav&wI{up7)%G z)Y*V3E*hQ*Nyn$xz~WrPeSL4-AY5GwX6^n&DJv_(>G#fgWxvXBP1Htfm4u2kCzlW_ z2}1eTVAsP;bJ%hl_!fvUB}?_By=Bh$R7wR#?a2g6Q!LE6Hhk%9)ZjAZ6$5#j?)R)dk|aQT7XshGipzMM)IJV1=WKhT^+wlFRyP zk|CTve5DVro8IsA0%hGd#2+AL_4C`PBD8m$0r~&_*6+KHY7qx z%m_r+Z5~SeEbkW_)m8;U5C-6cdrZ)BsTJ!RR=Ciz;>EEdc4ULY%80SWg>yn1`r;l` zGcQW*?b0FKe7nw?4NsVmlZfz|&(wA=(gPL)RYhCv^;P+)g1FL*?E7MxmL?F*f?fIH8Fz&)Wu~#LEH>lbVvzj-i_sqbua4ZL&Rzu#A44KeI4 zPr0;mh-0j`d{N`c-|Cs~l%g~J5)+oi%9h0(yxxM*0;sOii)hHI_cOTOAC0#4#D|tU z*4ZlE9@F4+nWQ(_!W`Pcc{|~!tz4^eyB=mszAjC=R*dd!Ixw}UAvBcAhh1%XEg8s# zf(I+e$}X&L&+(~!S~S|KgNw|)E-8~7)i9gJ>I$~9=MKp?9fYmLUxMQMjI@%6tde}F zX^2)RSoT+9BnR;j3II9ZKaX{D1C3k!K41Wl+&)MU4Y`od8Mj>2qyqITJP7^dd~6n{ z7=AJanKIjKHD=yQP!yy=bY^aD#*nkdOsY@t3xfKr^>RK)PKCgTd*v^Y`@uf(qrSiG zH7(KJf5>PK{v5%WTyNx=e5tUN^ZHg}3+nEQu|p2(K9tqmo3_4>#gXbSu)XHa2S|s~ zurQp_KiWcbY0;E}8-LucYBS6cCacTgeb#B_1aUxoVey2Mendv#m@PXa%rN$oLH04P z;JDEk08fYj$10UrHt8uFs!4aviCtUWoxJr* ze!WQZF~y-p6UV%mT9UP`htlxCK!3YXB*P>Z>ei04k(Xp`Rgt^3`3f>oRb%~UUv9`v zjtc%Hk}55EW===6+bcCKJZ{UzQR0fUNOc_9^RvbLZ;&^-0jR!jk2BzzB4G*~^YlI3 I=pLE(AJoXsiU0rr diff --git a/PyTorch/NLP/Transformer/distributed_train.py b/PyTorch/NLP/Transformer/distributed_train.py deleted file mode 100644 index 1150cdd9..00000000 --- a/PyTorch/NLP/Transformer/distributed_train.py +++ /dev/null @@ -1,63 +0,0 @@ -#!/usr/bin/env python3 -u -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - - - -import os -import socket -import subprocess - -from train import main as single_process_main -from fairseq import distributed_utils, options - - -def main(args): - if args.distributed_init_method is None and args.distributed_port > 0: - # We can determine the init method automatically for Slurm. - node_list = os.environ.get('SLURM_JOB_NODELIST') - if node_list is not None: - try: - hostnames = subprocess.check_output(['scontrol', 'show', 'hostnames', node_list]) - args.distributed_init_method = 'tcp://{host}:{port}'.format( - host=hostnames.split()[0].decode('utf-8'), - port=args.distributed_port) - args.distributed_rank = int(os.environ.get('SLURM_PROCID')) - args.device_id = int(os.environ.get('SLURM_LOCALID')) - except subprocess.CalledProcessError as e: # scontrol failed - raise e - except FileNotFoundError as e: # Slurm is not installed - pass - if args.distributed_init_method is None: - raise ValueError('--distributed-init-method or --distributed-port ' - 'must be specified for distributed training') - - args.distributed_rank = distributed_utils.distributed_init(args) - args.device_id = int(os.environ.get('LOCAL_RANK', args.local_rank)) - print('| initialized host {} as rank {} and device id {}'.format(socket.gethostname(), args.distributed_rank, args.device_id)) - single_process_main(args) - - -if __name__ == '__main__': - parser = options.get_training_parser() - args = options.parse_args_and_arch(parser) - main(args) diff --git a/PyTorch/NLP/Transformer/fairseq/__init__.py b/PyTorch/NLP/Transformer/fairseq/__init__.py deleted file mode 100644 index 94fc686a..00000000 --- a/PyTorch/NLP/Transformer/fairseq/__init__.py +++ /dev/null @@ -1,10 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -from .multiprocessing_pdb import pdb - -__all__ = ['pdb'] diff --git a/PyTorch/NLP/Transformer/fairseq/criterions.py b/PyTorch/NLP/Transformer/fairseq/criterions.py deleted file mode 100644 index a53fb3c9..00000000 --- a/PyTorch/NLP/Transformer/fairseq/criterions.py +++ /dev/null @@ -1,48 +0,0 @@ -import torch.nn.functional as F -from torch.nn.modules.loss import _Loss - - -class CrossEntropyCriterion(_Loss): - - def __init__(self, args): - super().__init__() - self.padding_idx = args.padding_idx - - def forward(self, norm_probs, target, reduce=True): - """Compute the loss for the given sample. - """ - lprobs = norm_probs.view(-1, norm_probs.size(-1)) - target = target.view(-1) - loss = F.nll_loss(lprobs, target, size_average=False, ignore_index=self.padding_idx, - reduce=reduce) - return loss - - -class LabelSmoothedCrossEntropyCriterion(_Loss): - - def __init__(self, args): - super().__init__() - self.eps = args.label_smoothing - self.padding_idx = args.padding_idx - - def forward(self, norm_probs, target, reduce=True): - """Compute the loss for the given sample. - """ - target = target.view(-1, 1) - lprobs = norm_probs.view(-1, norm_probs.size(-1)) - non_pad_mask = target.ne(self.padding_idx) - nll_loss = -lprobs.gather(dim=-1, index=target)[non_pad_mask] - smooth_loss = -lprobs.sum(dim=-1, keepdim=True)[non_pad_mask] - if reduce: - nll_loss = nll_loss.sum() - smooth_loss = smooth_loss.sum() - eps_i = self.eps / lprobs.size(-1) - loss = (1. - self.eps) * nll_loss + eps_i * smooth_loss - - return loss - - -CRITERION_REGISTRY = { - 'label_smoothed_cross_entropy' : LabelSmoothedCrossEntropyCriterion, - 'cross_entropy' : CrossEntropyCriterion, - } diff --git a/PyTorch/NLP/Transformer/fairseq/data/__init__.py b/PyTorch/NLP/Transformer/fairseq/data/__init__.py deleted file mode 100644 index e8c2d35c..00000000 --- a/PyTorch/NLP/Transformer/fairseq/data/__init__.py +++ /dev/null @@ -1,27 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from .dictionary import Dictionary -from .indexed_dataset import IndexedDataset, IndexedInMemoryDataset, IndexedRawTextDataset # noqa: F401 -from .language_pair_dataset import LanguagePairDataset, load_dataset_splits - -from .data_utils import EpochBatchIterator diff --git a/PyTorch/NLP/Transformer/fairseq/data/csrc/make_batches.cpp b/PyTorch/NLP/Transformer/fairseq/data/csrc/make_batches.cpp deleted file mode 100644 index efb2e3f2..00000000 --- a/PyTorch/NLP/Transformer/fairseq/data/csrc/make_batches.cpp +++ /dev/null @@ -1,77 +0,0 @@ -// Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -#include -#include -#include -#include - -namespace at { namespace native { - -namespace { - bool is_batch_full(int64_t num_tokens, int64_t max_tokens, int64_t max_sentences, int64_t batch_length){ - if (batch_length == 0){ - return false; - } else if (batch_length == max_sentences || num_tokens > max_tokens){ - return true; - } else { - return false; - } - - } -} - - -std::vector > make_batches(py::array_t src_lengths, py::array_t tgt_lengths, py::array_t idx_list, int64_t max_tokens, int64_t max_sentences, uint64_t bsz_mult, int64_t max_len){ - std::vector > batches; - auto src_l = src_lengths.unchecked<1>(); - auto tgt_l = tgt_lengths.unchecked<1>(); - auto idx_l = idx_list.unchecked<1>(); - AT_ASSERTM(src_l.shape(0) == tgt_l.shape(0), "tgt_list and src_list should have the same shape"); - AT_ASSERTM(idx_l.shape(0) == tgt_l.shape(0), "idx_list and tgt_list should have the same shape"); - ssize_t nelem = src_l.shape(0); - int64_t sample_len =0; - std::vector sample_lens; - std::vector batch; - for (ssize_t i=0; i < nelem; i++){ - int64_t idx = idx_l(i); - int64_t sample_num_tokens = std::max(src_l(idx), tgt_l(idx)); - if (sample_num_tokens > max_len) continue; - sample_len = std::max(sample_len, sample_num_tokens); - sample_lens.push_back(sample_num_tokens); - int64_t num_tokens = (batch.size() + 1) * sample_len; - if (is_batch_full(num_tokens, max_tokens, max_sentences, batch.size())){ - int64_t mode_len = std::max(batch.size() / bsz_mult * bsz_mult, batch.size() % bsz_mult); - std::vector new_batch; - new_batch.reserve(mode_len); - std::copy(batch.begin()+mode_len, batch.end(), std::back_inserter(new_batch)); - batch.erase(batch.begin()+mode_len, batch.end()); - sample_lens.erase(sample_lens.begin(), sample_lens.begin()+mode_len); -//sample_len always contains at least one element - sample_len = *std::max_element(sample_lens.begin(), sample_lens.end()); - batches.push_back(batch); - batch = new_batch; - } - batch.push_back(idx); - } - if (batch.size() > 0) batches.push_back(batch); - return batches; -} - - -}} - -PYBIND11_MODULE(TORCH_EXTENSION_NAME, m){ - m.def("make_batches", &at::native::make_batches); -} - diff --git a/PyTorch/NLP/Transformer/fairseq/data/data_utils.py b/PyTorch/NLP/Transformer/fairseq/data/data_utils.py deleted file mode 100644 index 3866ed1f..00000000 --- a/PyTorch/NLP/Transformer/fairseq/data/data_utils.py +++ /dev/null @@ -1,327 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import contextlib -import itertools -import os - -import numpy as np -import torch - -import fairseq.data.batch_C -import sys -from .dictionary import Dictionary - - -def infer_language_pair(path): - """Infer language pair from filename: .-.(...).idx""" - src, dst = None, None - for filename in os.listdir(path): - parts = filename.split('.') - if len(parts) >= 3 and len(parts[1].split('-')) == 2: - return parts[1].split('-') - return src, dst - - -def load_dictionaries(args): - if args.source_lang is None or args.target_lang is None: - args.source_lang, args.target_lang = infer_language_pair(args.data) - if args.source_lang is None or args.target_lang is None: - raise Exception('Could not infer language pair, please provide it explicitly') - - # load dictionaries - src_dict = Dictionary.load(os.path.join(args.data, 'dict.{}.txt'.format(args.source_lang))) - tgt_dict = Dictionary.load(os.path.join(args.data, 'dict.{}.txt'.format(args.target_lang))) - assert src_dict.pad() == tgt_dict.pad() - assert src_dict.eos() == tgt_dict.eos() - assert src_dict.unk() == tgt_dict.unk() - args.src_vocab_size = len(src_dict) - args.tgt_vocab_size = len(tgt_dict) - args.padding_idx = src_dict.pad() - print('| [{}] dictionary: {} types'.format(args.source_lang, len(src_dict))) - print('| [{}] dictionary: {} types'.format(args.target_lang, len(tgt_dict))) - return src_dict, tgt_dict - - -class ShardedIterator(object): - """A sharded wrapper around an iterable (padded to length).""" - - def __init__(self, iterable, num_shards, shard_id, fill_value=None): - if shard_id < 0 or shard_id >= num_shards: - raise ValueError('shard_id must be between 0 and num_shards') - - self._sharded_len = len(iterable) // num_shards - if len(iterable) % num_shards > 0: - self._sharded_len += 1 - - self.itr = itertools.zip_longest( - range(self._sharded_len), - itertools.islice(iterable, shard_id, len(iterable), num_shards), - fillvalue=fill_value, - ) - - def __len__(self): - return self._sharded_len - - def __iter__(self): - return self - - def __next__(self): - return next(self.itr)[1] - - -class CountingIterator(object): - """Wrapper around an iterable that maintains the iteration count.""" - - def __init__(self, iterable): - self.iterable = iterable - self.count = 0 - self.itr = iter(self) - - def __len__(self): - return len(self.iterable) - - def __iter__(self): - for x in self.iterable: - self.count += 1 - yield x - - def __next__(self): - return next(self.itr) - - def has_next(self): - return self.count < len(self) - - def skip(self, num_to_skip): - next(itertools.islice(self.itr, num_to_skip, num_to_skip), None) - return self - - -def collate_tokens(values, pad_idx, eos_idx, left_pad, move_eos_to_beginning=False, pad_sequence=1): - """Convert a list of 1d tensors into a padded 2d tensor.""" - #size = max(v.size(0) for v in values) - orig_size = max(v.size(0) for v in values) - size = 0 - if pad_sequence > 1: - size = orig_size // pad_sequence * pad_sequence - if orig_size % pad_sequence > 0: - size += pad_sequence - else: - size = orig_size - res = values[0].new(len(values), size).fill_(pad_idx) - - def copy_tensor(src, dst): - assert dst.numel() == src.numel() - if move_eos_to_beginning: - assert src[-1] == eos_idx - dst[0] = eos_idx - dst[1:] = src[:-1] - else: - dst.copy_(src) - - for i, v in enumerate(values): - copy_tensor(v, res[i][size - len(v):] if left_pad else res[i][:len(v)]) - return res - - -def collate(samples, pad_idx, eos_idx, left_pad_source=True, left_pad_target=False, pad_sequence=1): - if len(samples) == 0: - return {} - - def merge(key, left_pad, move_eos_to_beginning=False): - return collate_tokens( - [s[key] for s in samples], - pad_idx, eos_idx, left_pad, move_eos_to_beginning, - pad_sequence, - ) - - id = torch.LongTensor([s['id'] for s in samples]) - src_tokens = merge('source', left_pad=left_pad_source) - # sort by descending source length - src_lengths = torch.LongTensor([s['source'].numel() for s in samples]) - src_lengths, sort_order = src_lengths.sort(descending=True) - id = id.index_select(0, sort_order) - src_tokens = src_tokens.index_select(0, sort_order) - - prev_output_tokens = None - target = None - if samples[0].get('target', None) is not None: - target = merge('target', left_pad=left_pad_target) - # we create a shifted version of targets for feeding the - # previous output token(s) into the next decoder step - prev_output_tokens = merge( - 'target', - left_pad=left_pad_target, - move_eos_to_beginning=True, - ) - prev_output_tokens = prev_output_tokens.index_select(0, sort_order) - target = target.index_select(0, sort_order) - ntokens = sum(len(s['target']) for s in samples) - else: - ntokens = sum(len(s['source']) for s in samples) - - return { - 'id': id, - 'ntokens': ntokens, - 'net_input': { - 'src_tokens': src_tokens, - 'src_lengths': src_lengths, - 'prev_output_tokens': prev_output_tokens, - }, - 'target': target, - } - - -def get_dummy_batch(num_tokens, src_dict, tgt_dict, src_len=128, tgt_len=128, - left_pad_source=True, left_pad_target=False, pad_sequence=1): - bsz = num_tokens // max(src_len, tgt_len) - dummy_samples = [ - { - 'id': i, - 'source': src_dict.dummy_sentence(src_len), - 'target': tgt_dict.dummy_sentence(tgt_len) if tgt_dict is not None else None, - } - for i in range(bsz) - ] - return collate( - dummy_samples, pad_idx=src_dict.pad(), eos_idx=src_dict.eos(), - left_pad_source=left_pad_source, left_pad_target=left_pad_target, - pad_sequence=pad_sequence, - ) - - -class EpochBatchIterator(object): - """Iterate over a FairseqDataset and yield batches bucketed by size. - - Batches may contain sequences of different lengths. This iterator can be - reused across multiple epochs with the next_epoch_itr() method. - - Args: - dataset: a FairseqDataset - max_tokens: max number of tokens in each batch - max_sentences: max number of sentences in each batch - max_positions: max sentence length supported by the model - required_batch_size_multiple: require batch size to be a multiple of N - seed: seed for random number generator for reproducibility - num_shards: shard the data iterator into N shards - shard_id: which shard of the data iterator to return - """ - - def __init__( - self, dataset, max_tokens=None, max_sentences=None, max_positions=None, - required_batch_size_multiple=1, seed=1, - num_shards=1, shard_id=0, epoch=0 - ): - self.dataset = dataset - self.max_tokens = max_tokens if max_tokens is not None else float('Inf') - self.max_sentences = max_sentences if max_sentences is not None else float('Inf') - self.max_positions = max_positions - self.bsz_mult = required_batch_size_multiple - self.seed = seed - self.num_shards = num_shards - self.shard_id = shard_id - self.epoch = epoch - self._cur_epoch_itr = None - self._next_epoch_itr = None - - with numpy_seed(self.seed): - indices = self.dataset.ordered_indices(self.seed, self.epoch) -#need integer, rather than float('Inf') values - max_sentences = max_sentences if max_sentences is not None else sys.maxsize - max_positions_num = 1024 - max_tokens = max_tokens if max_tokens is not None else sys.maxsize - #Following line is workaround due to the fact we cannot pass None object as argument - tgt_sizes = self.dataset.tgt_sizes if self.dataset.tgt_sizes is not None else self.dataset.src_sizes - batches = fairseq.data.batch_C.make_batches( - self.dataset.src_sizes, tgt_sizes, indices, max_tokens, - max_sentences, self.bsz_mult, max_positions_num) - self.frozen_batches = tuple(batches) - - def __len__(self): - return len(self.frozen_batches) - - def next_epoch_itr(self, shuffle=True): - """Shuffle batches and return a new iterator over the dataset.""" - if self._next_epoch_itr is not None: - self._cur_epoch_itr = self._next_epoch_itr - self._next_epoch_itr = None - else: - self.epoch += 1 - self._cur_epoch_itr = self._get_iterator_for_epoch(self.epoch, shuffle) - return self._cur_epoch_itr - - def end_of_epoch(self): - return not self._cur_epoch_itr.has_next() - - @property - def iterations_in_epoch(self): - if self._cur_epoch_itr is not None: - return self._cur_epoch_itr.count - elif self._next_epoch_itr is not None: - return self._next_epoch_itr.count - return 0 - - def state_dict(self): - return { - 'epoch': self.epoch, - 'iterations_in_epoch': self.iterations_in_epoch, - } - - def load_state_dict(self, state_dict): - self.epoch = state_dict['epoch'] - itr_pos = state_dict.get('iterations_in_epoch', 0) - if itr_pos > 0: - # fast-forward epoch iterator - itr = self._get_iterator_for_epoch(self.epoch, state_dict.get('shuffle', True)) - if itr_pos < len(itr): - self._next_epoch_itr = itr.skip(itr_pos) - - def _get_iterator_for_epoch(self, epoch, shuffle): - if shuffle: - # set seed based on the seed and epoch number so that we get - # reproducible results when resuming from checkpoints - with numpy_seed(self.seed + epoch): - batches = list(self.frozen_batches) # copy - np.random.shuffle(batches) - else: - batches = self.frozen_batches - return CountingIterator(torch.utils.data.DataLoader( - self.dataset, - collate_fn=self.dataset.collater, - num_workers=1, - batch_sampler=ShardedIterator(batches, self.num_shards, self.shard_id, fill_value=[]), - )) - - -@contextlib.contextmanager -def numpy_seed(seed): - """Context manager which seeds the NumPy PRNG with the specified seed and - restores the state afterward""" - if seed is None: - yield - return - state = np.random.get_state() - np.random.seed(seed) - try: - yield - finally: - np.random.set_state(state) diff --git a/PyTorch/NLP/Transformer/fairseq/data/dictionary.py b/PyTorch/NLP/Transformer/fairseq/data/dictionary.py deleted file mode 100644 index bb9f2605..00000000 --- a/PyTorch/NLP/Transformer/fairseq/data/dictionary.py +++ /dev/null @@ -1,221 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -from collections import Counter -import os - -import torch - - -class Dictionary(object): - """A mapping from symbols to consecutive integers""" - def __init__(self, pad='', eos='', unk=''): - self.unk_word, self.pad_word, self.eos_word = unk, pad, eos - self.symbols = [] - self.count = [] - self.indices = {} - # dictionary indexing starts at 1 for consistency with Lua - self.add_symbol('') - self.pad_index = self.add_symbol(pad) - self.eos_index = self.add_symbol(eos) - self.unk_index = self.add_symbol(unk) - self.nspecial = len(self.symbols) - - def __eq__(self, other): - return self.indices == other.indices - - def __getitem__(self, idx): - if idx < len(self.symbols): - return self.symbols[idx] - return self.unk_word - - def __len__(self): - """Returns the number of symbols in the dictionary""" - return len(self.symbols) - - def index(self, sym): - """Returns the index of the specified symbol""" - if sym in self.indices: - return self.indices[sym] - return self.unk_index - - def string(self, tensor, bpe_symbol=None, escape_unk=False): - """Helper for converting a tensor of token indices to a string. - - Can optionally remove BPE symbols or escape words. - """ - if torch.is_tensor(tensor) and tensor.dim() == 2: - return '\n'.join(self.string(t) for t in tensor) - - def token_string(i): - if i == self.unk(): - return self.unk_string(escape_unk) - else: - return self[i] - - sent = ' '.join(token_string(i) for i in tensor if i != self.eos()) - if bpe_symbol is not None: - sent = (sent + ' ').replace(bpe_symbol, '').rstrip() - return sent - - def unk_string(self, escape=False): - """Return unknown string, optionally escaped as: <>""" - if escape: - return '<{}>'.format(self.unk_word) - else: - return self.unk_word - - def add_symbol(self, word, n=1): - """Adds a word to the dictionary""" - if word in self.indices: - idx = self.indices[word] - self.count[idx] = self.count[idx] + n - return idx - else: - idx = len(self.symbols) - self.indices[word] = idx - self.symbols.append(word) - self.count.append(n) - return idx - - def update(self, new_dict): - """Updates counts from new dictionary.""" - for word in new_dict.symbols: - idx2 = new_dict.indices[word] - if word in self.indices: - idx = self.indices[word] - self.count[idx] = self.count[idx] + new_dict.count[idx2] - else: - idx = len(self.symbols) - self.indices[word] = idx - self.symbols.append(word) - self.count.append(new_dict.count[idx2]) - - def finalize(self, threshold=-1, nwords=-1, padding_factor=8): - """Sort symbols by frequency in descending order, ignoring special ones. - - Args: - - threshold defines the minimum word count - - nwords defines the total number of words in the final dictionary, - including special symbols - - padding_factor can be used to pad the dictionary size to be a - multiple of 8, which is important on some hardware (e.g., Nvidia - Tensor Cores). - """ - if nwords <= 0: - nwords = len(self) - - new_indices = dict(zip(self.symbols[:self.nspecial], range(self.nspecial))) - new_symbols = self.symbols[:self.nspecial] - new_count = self.count[:self.nspecial] - - c = Counter(dict(zip(self.symbols[self.nspecial:], self.count[self.nspecial:]))) - for symbol, count in c.most_common(nwords - self.nspecial): - if count >= threshold: - new_indices[symbol] = len(new_symbols) - new_symbols.append(symbol) - new_count.append(count) - else: - break - - threshold_nwords = len(new_symbols) - if padding_factor > 1: - i = 0 - while threshold_nwords % padding_factor != 0: - symbol = 'madeupword{:04d}'.format(i) - new_indices[symbol] = len(new_symbols) - new_symbols.append(symbol) - new_count.append(0) - i += 1 - threshold_nwords += 1 - - assert len(new_symbols) % padding_factor == 0 - assert len(new_symbols) == len(new_indices) - - self.count = list(new_count) - self.symbols = list(new_symbols) - self.indices = new_indices - - def pad(self): - """Helper to get index of pad symbol""" - return self.pad_index - - def eos(self): - """Helper to get index of end-of-sentence symbol""" - return self.eos_index - - def unk(self): - """Helper to get index of unk symbol""" - return self.unk_index - - @classmethod - def loads(cls, s): - lines = s.strip().split('\n') - d = cls() - for line in lines: - idx = line.rfind(' ') - word = line[:idx] - count = int(line[idx + 1:]) - d.indices[word] = len(d.symbols) - d.symbols.append(word) - d.count.append(count) - return d - - @classmethod - def load(cls, f, ignore_utf_errors=False): - """Loads the dictionary from a text file with the format: - - ``` - - - ... - ``` - """ - if isinstance(f, str): - try: - if not ignore_utf_errors: - with open(f, 'r', encoding='utf-8') as fd: - return cls.load(fd) - else: - with open(f, 'r', encoding='utf-8', errors='ignore') as fd: - return cls.load(fd) - except FileNotFoundError as fnfe: - raise fnfe - except Exception: - raise Exception("Incorrect encoding detected in {}, please " - "rebuild the dataset".format(f)) - cont = f.read() - d = cls.loads(cont) - return d - - def save(self, f): - """Stores dictionary into a text file""" - if isinstance(f, str): - os.makedirs(os.path.dirname(f), exist_ok=True) - with open(f, 'w', encoding='utf-8') as fd: - return self.save(fd) - d = self.saves() - f.write(d) - - def saves(self): - rv = '' - for symbol, count in zip(self.symbols[self.nspecial:], self.count[self.nspecial:]): - rv += '{} {}\n'.format(symbol, count) - return rv - - def dummy_sentence(self, length): - t = torch.Tensor(length).uniform_(self.nspecial + 1, len(self)).long() - t[-1] = self.eos() - return t - - def get_metadata(self): - return {'len': self.__len__(), - 'pad': self.pad_index, - 'eos': self.eos_index, - 'unk': self.unk_index, - 'nspecial': self.nspecial - } diff --git a/PyTorch/NLP/Transformer/fairseq/data/fairseq_dataset.py b/PyTorch/NLP/Transformer/fairseq/data/fairseq_dataset.py deleted file mode 100644 index fe5809bf..00000000 --- a/PyTorch/NLP/Transformer/fairseq/data/fairseq_dataset.py +++ /dev/null @@ -1,35 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import torch.utils.data - - -class FairseqDataset(torch.utils.data.Dataset): - """A dataset that provides helpers for batching.""" - - def __getitem__(self, index): - raise NotImplementedError - - def __len__(self): - raise NotImplementedError - - def collater(self, samples): - """Merge a list of samples to form a mini-batch.""" - raise NotImplementedError - - - def num_tokens(self, index): - """Return an example's length (number of tokens), used for batching.""" - raise NotImplementedError - - def ordered_indices(self, seed=None, epoch=0): - """Ordered indices for batching.""" - raise NotImplementedError - - def valid_size(self, index, max_positions): - """Check if an example's size is valid according to max_positions.""" - raise NotImplementedError diff --git a/PyTorch/NLP/Transformer/fairseq/data/indexed_dataset.py b/PyTorch/NLP/Transformer/fairseq/data/indexed_dataset.py deleted file mode 100644 index 8b940dea..00000000 --- a/PyTorch/NLP/Transformer/fairseq/data/indexed_dataset.py +++ /dev/null @@ -1,206 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import os -import struct - -import numpy as np -import torch - -from fairseq.tokenizer import Tokenizer - - -def read_longs(f, n): - a = np.empty(n, dtype=np.int64) - f.readinto(a) - return a - - -def write_longs(f, a): - f.write(np.array(a, dtype=np.int64)) - - -dtypes = { - 1: np.uint8, - 2: np.int8, - 3: np.int16, - 4: np.int32, - 5: np.int64, - 6: np.float, - 7: np.double, -} - - -def code(dtype): - for k in dtypes.keys(): - if dtypes[k] == dtype: - return k - - -def index_file_path(prefix_path): - return prefix_path + '.idx' - - -def data_file_path(prefix_path): - return prefix_path + '.bin' - - -class IndexedDataset(torch.utils.data.Dataset): - """Loader for TorchNet IndexedDataset""" - - def __init__(self, path, fix_lua_indexing=False): - super().__init__() - self.fix_lua_indexing = fix_lua_indexing - with open(index_file_path(path), 'rb') as f: - magic = f.read(8) - assert magic == b'TNTIDX\x00\x00' - version = f.read(8) - assert struct.unpack('= self.size: - raise IndexError('index out of range') - - def __del__(self): - self.data_file.close() - - def __getitem__(self, i): - self.check_index(i) - tensor_size = self.sizes[self.dim_offsets[i]:self.dim_offsets[i + 1]] - a = np.empty(tensor_size, dtype=self.dtype) - self.data_file.seek(self.data_offsets[i] * self.element_size) - self.data_file.readinto(a) - item = torch.from_numpy(a).long() - if self.fix_lua_indexing: - item -= 1 # subtract 1 for 0-based indexing - return item - - def __len__(self): - return self.size - - @staticmethod - def exists(path): - return ( - os.path.exists(index_file_path(path)) and - os.path.exists(data_file_path(path)) - ) - - -class IndexedInMemoryDataset(IndexedDataset): - """Loader for TorchNet IndexedDataset, keeps all the data in memory""" - - def read_data(self, path): - self.data_file = open(data_file_path(path), 'rb') - self.buffer = np.empty(self.data_offsets[-1], dtype=self.dtype) - self.data_file.readinto(self.buffer) - self.data_file.close() - if self.fix_lua_indexing: - self.buffer -= 1 # subtract 1 for 0-based indexing - - def __del__(self): - pass - - def __getitem__(self, i): - self.check_index(i) - tensor_size = self.sizes[self.dim_offsets[i]:self.dim_offsets[i + 1]] - a = np.empty(tensor_size, dtype=self.dtype) - np.copyto(a, self.buffer[self.data_offsets[i]:self.data_offsets[i + 1]]) - return torch.from_numpy(a).long() - - -class IndexedRawTextDataset(IndexedDataset): - """Takes a text file as input and binarizes it in memory at instantiation. - Original lines are also kept in memory""" - - def __init__(self, path, dictionary, append_eos=True, reverse_order=False): - self.tokens_list = [] - self.lines = [] - self.sizes = [] - self.append_eos = append_eos - self.reverse_order = reverse_order - self.read_data(path, dictionary) - self.size = len(self.tokens_list) - - def read_data(self, path, dictionary): - with open(path, 'r') as f: - for line in f: - self.lines.append(line.strip('\n')) - tokens = Tokenizer.tokenize( - line, dictionary, add_if_not_exist=False, - append_eos=self.append_eos, reverse_order=self.reverse_order, - ).long() - self.tokens_list.append(tokens) - self.sizes.append(len(tokens)) - self.sizes = np.array(self.sizes) - - def __getitem__(self, i): - self.check_index(i) - return self.tokens_list[i] - - def get_original_text(self, i): - self.check_index(i) - return self.lines[i] - - def __del__(self): - pass - - def __len__(self): - return self.size - - @staticmethod - def exists(path): - return os.path.exists(path) - - -class IndexedDatasetBuilder(object): - element_sizes = { - np.uint8: 1, - np.int8: 1, - np.int16: 2, - np.int32: 4, - np.int64: 8, - np.float: 4, - np.double: 8 - } - - def __init__(self, out_file, dtype=np.int32): - self.out_file = open(out_file, 'wb') - self.dtype = dtype - self.data_offsets = [0] - self.dim_offsets = [0] - self.sizes = [] - self.element_size = self.element_sizes[self.dtype] - - def add_item(self, tensor): - # +1 for Lua compatibility - bytes = self.out_file.write(np.array(tensor.numpy() + 1, dtype=self.dtype)) - self.data_offsets.append(self.data_offsets[-1] + bytes / self.element_size) - for s in tensor.size(): - self.sizes.append(s) - self.dim_offsets.append(self.dim_offsets[-1] + len(tensor.size())) - - def finalize(self, index_file): - self.out_file.close() - index = open(index_file, 'wb') - index.write(b'TNTIDX\x00\x00') - index.write(struct.pack(' 0, "Padding multiple has to be greater than 0" - size = 0 - if self.pad_sequence > 1: - size = orig_size // self.pad_sequence * self.pad_sequence - if orig_size % self.pad_sequence > 0: - size += self.pad_sequence - else: - size = orig_size - return size - #return max(self.src_sizes[index], self.tgt_sizes[index] if self.tgt_sizes is not None else 0) - - def ordered_indices(self, seed=None, epoch=1): - """Ordered indices for batching.""" - if self.shuffle: - indices = np.random.RandomState(seed + epoch).permutation(len(self)) - else: - indices = np.arange(len(self)) - if self.tgt_sizes is not None: - indices = indices[np.argsort(self.tgt_sizes[indices], kind='mergesort')] - return indices[np.argsort(self.src_sizes[indices], kind='mergesort')] - - def valid_size(self, index, max_positions): - """Check if an example's size is valid according to max_positions.""" - max_source_positions, max_target_positions = self._get_max_positions(max_positions) - return ( - self.src_sizes[index] <= max_source_positions and - (self.tgt_sizes is None or self.tgt_sizes[index] <= max_target_positions) - ) - - def _get_max_positions(self, max_positions): - if max_positions is None: - return self.max_source_positions, self.max_target_positions - assert len(max_positions) == 2 - max_src_pos, max_tgt_pos = max_positions - return min(self.max_source_positions, max_src_pos), min(self.max_target_positions, max_tgt_pos) - - -def load_dataset(args, datasets, split, src_dict, tgt_dict, combine=False): - """Load a dataset split.""" - - def split_exists(split, src, tgt, lang): - filename = os.path.join(args.data, '{}.{}-{}.{}'.format(split, src, tgt, lang)) - if args.raw_text and IndexedRawTextDataset.exists(filename): - return True - elif not args.raw_text and IndexedInMemoryDataset.exists(filename): - return True - return False - - def indexed_dataset(path, dictionary): - if args.raw_text: - return IndexedRawTextDataset(path, dictionary) - elif IndexedInMemoryDataset.exists(path): - return IndexedInMemoryDataset(path, fix_lua_indexing=True) - return None - - src_datasets = [] - tgt_datasets = [] - - for k in itertools.count(): - split_k = split + (str(k) if k > 0 else '') - - # infer langcode - src, tgt = args.source_lang, args.target_lang - if split_exists(split_k, src, tgt, src): - prefix = os.path.join(args.data, '{}.{}-{}.'.format(split_k, src, tgt)) - elif split_exists(split_k, tgt, src, src): - prefix = os.path.join(args.data, '{}.{}-{}.'.format(split_k, tgt, src)) - else: - if k > 0: - break - else: - raise FileNotFoundError('Dataset not found: {} ({})'.format(split, args.data)) - - src_datasets.append(indexed_dataset(prefix + src, src_dict)) - tgt_datasets.append(indexed_dataset(prefix + tgt, tgt_dict)) - - print('| {} {} {} examples'.format(args.data, split_k, len(src_datasets[-1]))) - - if not combine: - break - - assert len(src_datasets) == len(tgt_datasets) - - if len(src_datasets) == 1: - src_dataset, tgt_dataset = src_datasets[0], tgt_datasets[0] - src_sizes = src_dataset.sizes - tgt_sizes = tgt_dataset.sizes - else: - src_dataset = ConcatDataset(src_datasets) - tgt_dataset = ConcatDataset(tgt_datasets) - src_sizes = np.concatenate([ds.sizes for ds in src_datasets]) - tgt_sizes = np.concatenate([ds.sizes for ds in tgt_datasets]) - - datasets[split] = LanguagePairDataset( - src_dataset, src_sizes, src_dict, - tgt_dataset, tgt_sizes, tgt_dict, - left_pad_source=args.left_pad_source, - left_pad_target=args.left_pad_target, - max_source_positions=args.max_source_positions, - max_target_positions=args.max_target_positions, - pad_sequence=args.pad_sequence, - ) - - -def load_dataset_splits(args, splits, src_dict, tgt_dict): - datasets = {} - for split in splits: - if split == 'train': - load_dataset(args, datasets, split, src_dict, tgt_dict, combine=True) - else: - for k in itertools.count(): - split_k = split + (str(k) if k > 0 else '') - try: - load_dataset(args, datasets, split_k, src_dict, tgt_dict, combine=False) - except FileNotFoundError as e: - if k > 0: - break - raise e - return datasets diff --git a/PyTorch/NLP/Transformer/fairseq/data/token_block_dataset.py b/PyTorch/NLP/Transformer/fairseq/data/token_block_dataset.py deleted file mode 100644 index 748df798..00000000 --- a/PyTorch/NLP/Transformer/fairseq/data/token_block_dataset.py +++ /dev/null @@ -1,108 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import math - -import numpy as np -import torch - - -class TokenBlockDataset(torch.utils.data.Dataset): - """Break a 1d tensor of tokens into blocks. - - The blocks are fetched from the original tensor so no additional memory is allocated. - - Args: - tokens: 1d tensor of tokens to break into blocks - sizes: sentence lengths (required for 'complete' and 'eos') - block_size: maximum block size (ignored in 'eos' break mode) - break_mode: Mode used for breaking tokens. Values can be one of: - - 'none': break tokens into equally sized blocks (up to block_size) - - 'complete': break tokens into blocks (up to block_size) such that - blocks contains complete sentences, although block_size may be - exceeded if some sentences exceed block_size - - 'eos': each block contains one sentence (block_size is ignored) - include_targets: return next tokens as targets - """ - - def __init__(self, tokens, sizes, block_size, break_mode=None, include_targets=False): - super().__init__() - - self.tokens = tokens - self.total_size = len(tokens) - self.include_targets = include_targets - self.slice_indices = [] - - if break_mode is None or break_mode == 'none': - length = math.ceil(len(tokens) / block_size) - - def block_at(i): - start = i * block_size - end = min(start + block_size, len(tokens)) - return (start, end) - - self.slice_indices = [block_at(i) for i in range(length)] - elif break_mode == 'complete': - assert sizes is not None and sum(sizes) == len(tokens), '{} != {}'.format(sum(sizes), len(tokens)) - tok_idx = 0 - sz_idx = 0 - curr_size = 0 - while sz_idx < len(sizes): - if curr_size + sizes[sz_idx] <= block_size or curr_size == 0: - curr_size += sizes[sz_idx] - sz_idx += 1 - else: - self.slice_indices.append((tok_idx, tok_idx + curr_size)) - tok_idx += curr_size - curr_size = 0 - if curr_size > 0: - self.slice_indices.append((tok_idx, tok_idx + curr_size)) - elif break_mode == 'eos': - assert sizes is not None and sum(sizes) == len(tokens), '{} != {}'.format(sum(sizes), len(tokens)) - curr = 0 - for sz in sizes: - # skip samples with just 1 example (which would be just the eos token) - if sz > 1: - self.slice_indices.append((curr, curr + sz)) - curr += sz - else: - raise ValueError('Invalid break_mode: ' + break_mode) - - self.sizes = np.array([e - s for s, e in self.slice_indices]) - - def __getitem__(self, index): - s, e = self.slice_indices[index] - - item = torch.LongTensor(self.tokens[s:e]) - - if self.include_targets: - # target is the sentence, for source, rotate item one token to the left (would start with eos) - if s == 0: - source = np.concatenate([self.tokens[-1:], self.tokens[0:e - 1]]) - else: - source = self.tokens[s - 1:e - 1] - - return torch.LongTensor(source), item - return item - - def __len__(self): - return len(self.slice_indices) diff --git a/PyTorch/NLP/Transformer/fairseq/ddp_trainer.py b/PyTorch/NLP/Transformer/fairseq/ddp_trainer.py deleted file mode 100644 index 21c27992..00000000 --- a/PyTorch/NLP/Transformer/fairseq/ddp_trainer.py +++ /dev/null @@ -1,305 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -""" -Train a network across multiple GPUs. -""" - -import math -from collections import defaultdict -from itertools import chain - -import torch -import torch.nn.functional as F -from torch.cuda import amp -from apex.parallel import DistributedDataParallel as DDP - -from fairseq import distributed_utils, optim, utils -from fairseq.optim import lr_scheduler -from fairseq.meters import TimeMeter, AverageMeter -from fairseq.criterions import CRITERION_REGISTRY - -import dllogger as DLLogger - - -class DDPTrainer(): - """Main class for data parallel training. - - This class supports data parallel training, where multiple workers each - have a full model replica and gradients are accumulated synchronously via - torch.distributed.all_reduce. - """ - - def __init__(self, args, model): - - if not torch.cuda.is_available(): - raise NotImplementedError('Training on CPU is not supported') - - self.args = args - - self.model = model.cuda() - self.criterion = CRITERION_REGISTRY[args.criterion](args).cuda() - self.optimizer = optim.build_optimizer(self.args, self.model.parameters()) - self.lr_scheduler = lr_scheduler.build_lr_scheduler(self.args, self.optimizer) - self.scaler = amp.GradScaler(enabled=self.args.amp, init_scale=2**15) - - if self.args.distributed_world_size > 1: - self.model = DDP(model) - - self._buffered_stats = defaultdict(lambda: []) - self._num_updates = 0 - self._optim_history = None - self.throughput_meter = TimeMeter() - self.avg_loss_meter = AverageMeter() - - def save_checkpoint(self, filename, extra_state): - """Save all training state in a checkpoint file.""" - if distributed_utils.is_master(self.args): # only save one checkpoint - utils.save_state( - filename, self.args, self.get_model(), self.criterion, self.optimizer, - self.lr_scheduler, self._num_updates, self._optim_history, extra_state, - ) - - def load_checkpoint(self, filename, load_optim=True): - """Load all training state from a checkpoint file.""" - extra_state, optim_history, last_optim_state = \ - utils.load_model_state(filename, self.get_model()) - - if last_optim_state is not None: - # rebuild optimizer after loading model, since params may have changed - #self.optimizer = optim.build_optimizer(self.args, self.model.parameters()) - self.lr_scheduler = lr_scheduler.build_lr_scheduler(self.args, self.optimizer) - - if load_optim: - self._optim_history = optim_history - # only reload optimizer and lr_scheduler if they match - last_optim = self._optim_history[-1] - if last_optim['criterion_name'] == self.criterion.__class__.__name__: - self.lr_scheduler.load_state_dict(last_optim['lr_scheduler_state']) - if last_optim['optimizer_name'] == self.optimizer.__class__.__name__: - self.optimizer.load_state_dict(last_optim_state) - - self._num_updates = last_optim['num_updates'] - - return extra_state - - def train_step(self, sample, update_params=True, last_step=False): - """Do forward, backward and parameter update.""" - # Set seed based on args.seed and the update number so that we get - # reproducible results when resuming from checkpoints - seed = self.args.seed + self.get_num_updates() - torch.manual_seed(seed) - torch.cuda.manual_seed(seed) - - self.model.train() - if isinstance(self.model, DDP): - if last_step: - self.model.disable_allreduce() - else: - self.model.enable_allreduce() - - # forward and backward pass - sample = self._prepare_sample(sample) - loss, oom_fwd = self._forward(sample) - - # If this is a last batch forward pass is skipped on some workers - # Batch with sample_size 0 is not accounted for in weighted loss - logging_output = { - 'ntokens': sample['ntokens'] if sample is not None else 0, - 'nsentences': sample['target'].size(0) if sample is not None else 0, - 'loss': utils.item(loss.data) if loss is not None else 0, - } - sample_size = sample['ntokens'] if sample is not None else 0 - oom_bwd = self._backward(loss) - - # buffer stats and logging outputs - self._buffered_stats['sample_sizes'].append(sample_size) - self._buffered_stats['logging_outputs'].append(logging_output) - self._buffered_stats['ooms_fwd'].append(oom_fwd) - self._buffered_stats['ooms_bwd'].append(oom_bwd) - - # update parameters - if update_params and not last_step: - # gather logging outputs from all replicas - sample_sizes = self._buffered_stats['sample_sizes'] - logging_outputs = self._buffered_stats['logging_outputs'] - ooms_fwd = self._buffered_stats['ooms_fwd'] - ooms_bwd = self._buffered_stats['ooms_bwd'] - if self.args.distributed_world_size > 1: - sample_sizes, logging_outputs, ooms_fwd, ooms_bwd = map( - lambda l: list(chain.from_iterable(l)), - zip(*distributed_utils.all_gather_list( - (sample_sizes, logging_outputs, ooms_fwd, ooms_bwd) - )) - ) - ooms_fwd = sum(ooms_fwd) - ooms_bwd = sum(ooms_bwd) - ooms = ooms_fwd + ooms_bwd # this is always <= distributed_world_size - - if ooms == self.args.distributed_world_size: - print('| WARNING: OOM in all workers, skipping batch') - self.zero_grad() - return - - # aggregate stats and logging outputs - grad_denom = sum(sample_sizes) - for p in self.model.parameters(): - if p.requires_grad and p.grad is not None: - p.grad /= grad_denom - - self._opt() - - # Handle logging - ntokens = sum(log.get('ntokens', 0) for log in logging_outputs) - self.throughput_meter.update(ntokens) - info_log_data = { - 'tokens/s': self.throughput_meter.avg, - 'tokens': ntokens, - 'loss': sum(log.get('loss', 0) for log in logging_outputs) / ntokens / math.log(2) - } - self.avg_loss_meter.update(info_log_data['loss']) - debug_log_data = { - 'batch_size': sum(log.get('nsentences', 0) for log in logging_outputs), - 'lr': self.get_lr(), - 'grad_denom': grad_denom, - 'updates': 1 - } - - DLLogger.log(step=self._num_updates, data=info_log_data, verbosity=0) - DLLogger.log(step=self._num_updates, data=debug_log_data, verbosity=1) - - self.clear_buffered_stats() - - def _forward(self, sample): - loss = None - oom = 0 - try: - if sample is not None: - with amp.autocast(enabled=self.args.amp): - # calculate loss and sample size - logits, _ = self.model(**sample['net_input']) - target = sample['target'] - probs = F.log_softmax(logits, dim=-1, dtype=torch.float32) - loss = self.criterion(probs, target) - except RuntimeError as e: - if 'out of memory' in str(e): - print('| WARNING: ran out of memory in worker {}, skipping batch'.format( - self.args.distributed_rank), force=True) - oom = 1 - loss = None - else: - raise e - return loss, oom - - def _backward(self, loss): - oom = 0 - if loss is not None: - try: - self.scaler.scale(loss).backward() - except RuntimeError as e: - if 'out of memory' in str(e): - print('| WARNING: ran out of memory in worker {}, skipping batch'.format( - self.args.distributed_rank), force=True) - oom = 1 - self.zero_grad() - else: - raise e - return oom - - def _opt(self): - # take an optimization step - self.scaler.step(self.optimizer.optimizer) - self.scaler.update() - self.zero_grad() - self._num_updates += 1 - - # update learning rate - self.lr_scheduler.step_update(self._num_updates) - - def valid_step(self, sample): - """Do forward pass in evaluation mode.""" - self.model.eval() - # forward pass - sample = self._prepare_sample(sample) - with torch.no_grad(): - loss, oom_fwd = self._forward(sample) - logging_output = { - 'ntokens': sample['ntokens'] if sample is not None else 0, - 'nsentences': sample['target'].size(0) if sample is not None else 0, - } - loss = loss.item() if loss is not None else 0 - assert not oom_fwd, 'Ran out of memory during validation' - - # gather logging outputs from all GPUs - if self.args.distributed_world_size > 1: - losses, logging_outputs = zip(*distributed_utils.all_gather_list( - (loss, logging_output) - )) - else: - losses = [loss] - logging_outputs = [logging_output] - - weight = sum(log.get('ntokens', 0) for log in logging_outputs) - scaled_loss = sum(losses) / weight / math.log(2) - - return scaled_loss - - def dummy_train_step(self, dummy_batch): - """Dummy training step for warming caching allocator.""" - self.train_step(dummy_batch, update_params=False) - self.zero_grad() - self.clear_buffered_stats() - - def zero_grad(self): - self.optimizer.zero_grad() - - def clear_buffered_stats(self): - self._buffered_stats.clear() - - def lr_step(self, epoch, val_loss=None): - """Adjust the learning rate based on the validation loss.""" - return self.lr_scheduler.step(epoch, val_loss) - - def lr_step_update(self, num_updates): - """Update the learning rate after each update.""" - return self.lr_scheduler.step_update(num_updates) - - def get_lr(self): - """Get the current learning rate.""" - return self.optimizer.get_lr() - - def get_throughput_meter(self): - """Get the throughput meter""" - return self.throughput_meter - - def get_model(self): - """Get the model replica.""" - return self.model.module if isinstance(self.model, DDP) else self.model - - def get_num_updates(self): - """Get the number of parameters updates.""" - return self._num_updates - - def _prepare_sample(self, sample): - if not sample: - return None - return utils.move_to_cuda(sample) diff --git a/PyTorch/NLP/Transformer/fairseq/distributed_utils.py b/PyTorch/NLP/Transformer/fairseq/distributed_utils.py deleted file mode 100644 index 4b4c17c6..00000000 --- a/PyTorch/NLP/Transformer/fairseq/distributed_utils.py +++ /dev/null @@ -1,111 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import pickle -import os -import socket - -import torch.distributed - -from fairseq import utils - - -def is_master(args): - return args.distributed_rank == 0 - - -def distributed_init(args): - if args.distributed_world_size == 1: - raise ValueError('Cannot initialize distributed with distributed_world_size=1') - - print('| distributed init (rank {}): {}'.format( - args.distributed_rank, args.distributed_init_method), flush=True) - print("| distributed env init. MASTER_ADDR: " + os.environ['MASTER_ADDR'] + - ", MASTER_PORT: " + os.environ['MASTER_PORT'] + - ", WORLD_SIZE: " + os.environ['WORLD_SIZE'] + ", RANK: " + os.environ['RANK'], flush=True) - torch.distributed.init_process_group( - backend=args.distributed_backend, init_method='env://') - print("| distributed init done!", flush=True) - args.distributed_world_size = int(os.environ['WORLD_SIZE']) - - args.distributed_rank = torch.distributed.get_rank() - args.device_id = int(os.environ.get('LOCAL_RANK', args.local_rank)) - suppress_output(args) - print('| initialized host {} as rank {} and device id {}' - .format(socket.gethostname(), args.distributed_rank, args.device_id)) - - return args.distributed_rank - - -def suppress_output(main_args): - """Suppress printing on the current device. Force printing with `force=True`.""" - import builtins as __builtin__ - builtin_print = __builtin__.print - - def print_master(*args, **kwargs): - if 'force' in kwargs: - kwargs.pop('force') - builtin_print(*args, **kwargs) - - def print(*args, **kwargs): - if 'force' in kwargs: - force = kwargs.pop('force') - if force: - builtin_print(*args, **kwargs) - if is_master(main_args): - __builtin__.print = print_master - else: - __builtin__.print = print - - -def all_gather_list(data, max_size=16384): - """Gathers arbitrary data from all nodes into a list.""" - world_size = torch.distributed.get_world_size() - if not hasattr(all_gather_list, '_in_buffer') or \ - max_size != len(all_gather_list._in_buffer): - all_gather_list._in_buffer = torch.cuda.ByteTensor(max_size) - all_gather_list._out_buffers = [ - torch.cuda.ByteTensor(max_size) - for i in range(world_size) - ] - in_buffer = all_gather_list._in_buffer - out_buffers = all_gather_list._out_buffers - - enc = pickle.dumps(data) - enc_size = len(enc) - if enc_size + 2 > max_size: - raise ValueError('encoded data exceeds max_size: {}'.format(enc_size + 2)) - assert max_size < 255 * 256 - in_buffer[0] = enc_size // 255 # this encoding works for max_size < 65k - in_buffer[1] = enc_size % 255 - in_buffer[2:enc_size + 2] = torch.ByteTensor(list(enc)) - - torch.distributed.all_gather(out_buffers, in_buffer.cuda()) - - result = [] - for i in range(world_size): - out_buffer = out_buffers[i] - size = (255 * utils.item(out_buffer[0])) + utils.item(out_buffer[1]) - result.append( - pickle.loads(bytes(out_buffer[2:size + 2].tolist())) - ) - return result diff --git a/PyTorch/NLP/Transformer/fairseq/log_helper.py b/PyTorch/NLP/Transformer/fairseq/log_helper.py deleted file mode 100644 index 8b66afd9..00000000 --- a/PyTorch/NLP/Transformer/fairseq/log_helper.py +++ /dev/null @@ -1,204 +0,0 @@ -import os -import atexit -import time -import itertools - -from collections import OrderedDict - -import dllogger -from dllogger import Backend, JSONStreamBackend -from tensorboardX import SummaryWriter - - -class AverageMeter(): - def __init__(self): - self.reset() - - def reset(self): - self.updated = False - self.avg = 0 - self.sum = 0 - self.count = 0 - - def update(self, value): - self.updated = True - if isinstance(value, (tuple, list)): - val = value[0] - n = value[1] - else: - val = value - n = 1 - self.sum += val * n - self.count += n - self.avg = self.sum / self.count - - @property - def value(self): - return self.avg - - -class PerformanceMeter(): - def __init__(self): - self.reset() - - def reset(self): - self.updated = False - self.start = time.time() - self.n = 0 - - def update(self, val=1): - self.updated = True - self.n += val - - @property - def value(self): - return self.n / self.elapsed_time - - @property - def elapsed_time(self): - return time.time() - self.start - - -METRIC = {'average': AverageMeter, 'performance': PerformanceMeter} - - -class AggregatorBackend(Backend): - def __init__(self, verbosity, agg_dict): - super().__init__(verbosity=verbosity) - agg_dict = OrderedDict({k: v if isinstance(v, (tuple, list)) else (v,) for k, v in agg_dict.items()}) - self.metrics = OrderedDict({k: [METRIC[x]() for x in v] for k, v in agg_dict.items()}) - self.metrics.flushed = True - self.step = 0 - self.epoch = 0 - self.start_time = time.time() - - @property - def log_level(self): - return self._log_level - - def metadata(self, timestamp, elapsedtime, metric, metadata): - pass - - def _reset_perf_meter(self, name): - for agg in self.metrics[name]: - if isinstance(agg, PerformanceMeter): - agg.reset() - - def reset_perf_meters(self): - for name in self.metrics.keys(): - self._reset_perf_meter(name) - - def log(self, timestamp, elapsedtime, step, data): - self.step = step - if 'epoch' in data.keys(): - self.epoch = data['epoch'] - for k, v in data.items(): - if k not in self.metrics.keys(): - continue - self.metrics.flushed = False - for ag in self.metrics[k]: - ag.update(v) - - def flush(self): - if self.metrics.flushed: - return - result_string = 'Transformer | epoch {} | step {} |'.format(self.epoch, self.step) - for name, aggregators in self.metrics.items(): - for agg in aggregators: - if not agg.updated: - continue - if isinstance(agg, AverageMeter): - _name = 'avg ' + name - elif isinstance(agg, PerformanceMeter): - _name = name + '/s' - - result_string += _name + ' {:.3f} |'.format(agg.value) - agg.reset() - - result_string += 'walltime {:.3f} |'.format(time.time() - self.start_time) - self.metrics.flushed = True - print(result_string) - - -class TensorBoardBackend(Backend): - def __init__(self, verbosity, log_dir): - super().__init__(verbosity=verbosity) - self.summary_writer = SummaryWriter(log_dir=os.path.join(log_dir, 'TB_summary'), - flush_secs=120, - max_queue=200 - ) - atexit.register(self.summary_writer.close) - - @property - def log_level(self): - return self._log_level - - def metadata(self, timestamp, elapsedtime, metric, metadata): - pass - - def log(self, timestamp, elapsedtime, step, data): - if not isinstance(step, int): - return - for k, v in data.items(): - self.summary_writer.add_scalar(k, v, step) - - def flush(self): - pass - - -def setup_logger(args): - aggregator_dict = OrderedDict([ - ('loss', 'average'), - ('weighted_loss', 'average'), - ('tokens', ('average', 'performance')), - ('updates', 'performance'), - ('gnorm', 'average') - ]) - os.makedirs(args.save_dir, exist_ok=True) - log_path = os.path.join(args.save_dir, args.stat_file) - - if os.path.exists(log_path): - for i in itertools.count(): - s_fname = args.stat_file.split('.') - fname = '.'.join(s_fname[:-1]) + f'_{i}.' + s_fname[-1] if len(s_fname) > 1 else args.stat_file + f'.{i}' - log_path = os.path.join(args.save_dir, fname) - if not os.path.exists(log_path): - break - - if not args.distributed_world_size > 1 or args.distributed_rank == 0: - dllogger.init(backends=[JSONStreamBackend(verbosity=1, filename=log_path), - AggregatorBackend(verbosity=0, agg_dict=aggregator_dict), - TensorBoardBackend(verbosity=1, log_dir=args.save_dir)]) - else: - dllogger.init(backends=[]) - for k, v in vars(args).items(): - dllogger.log(step='PARAMETER', data={k: v}, verbosity=0) - - container_setup_info = get_framework_env_vars() - dllogger.log(step='PARAMETER', data=container_setup_info, verbosity=0) - - dllogger.metadata('loss', {'unit': 'nat', 'GOAL': 'MINIMIZE', 'STAGE': 'TRAIN'}) - dllogger.metadata('val_loss', {'unit': 'nat', 'GOAL': 'MINIMIZE', 'STAGE': 'VAL'}) - dllogger.metadata('speed', {'unit': 'tokens/s', 'format': ':.3f', 'GOAL': 'MAXIMIZE', 'STAGE': 'TRAIN'}) - dllogger.metadata('accuracy', {'unit': 'bleu', 'format': ':.2f', 'GOAL': 'MAXIMIZE', 'STAGE': 'VAL'}) - - -def get_framework_env_vars(): - return { - 'NVIDIA_PYTORCH_VERSION': os.environ.get('NVIDIA_PYTORCH_VERSION'), - 'PYTORCH_VERSION': os.environ.get('PYTORCH_VERSION'), - 'CUBLAS_VERSION': os.environ.get('CUBLAS_VERSION'), - 'NCCL_VERSION': os.environ.get('NCCL_VERSION'), - 'CUDA_DRIVER_VERSION': os.environ.get('CUDA_DRIVER_VERSION'), - 'CUDNN_VERSION': os.environ.get('CUDNN_VERSION'), - 'CUDA_VERSION': os.environ.get('CUDA_VERSION'), - 'NVIDIA_PIPELINE_ID': os.environ.get('NVIDIA_PIPELINE_ID'), - 'NVIDIA_BUILD_ID': os.environ.get('NVIDIA_BUILD_ID'), - 'NVIDIA_TF32_OVERRIDE': os.environ.get('NVIDIA_TF32_OVERRIDE'), - } - - -def reset_perf_meters(): - for backend in dllogger.GLOBAL_LOGGER.backends: - if isinstance(backend, AggregatorBackend): - backend.reset_perf_meters() diff --git a/PyTorch/NLP/Transformer/fairseq/meters.py b/PyTorch/NLP/Transformer/fairseq/meters.py deleted file mode 100644 index 8b3753ec..00000000 --- a/PyTorch/NLP/Transformer/fairseq/meters.py +++ /dev/null @@ -1,87 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import time - - -class AverageMeter(object): - """Computes and stores the average and current value""" - def __init__(self): - self.reset() - - def reset(self): - self.val = 0 - self.avg = 0 - self.sum = 0 - self.count = 0 - - def update(self, val, n=1): - self.val = val - self.sum += val * n - self.count += n - self.avg = self.sum / self.count - - -class TimeMeter(object): - """Computes the average occurrence of some event per second""" - def __init__(self, init=0): - self.reset(init) - - def reset(self, init=0): - self.init = init - self.start = time.time() - self.n = 0 - self.last_update = time.time() - - def update(self, val=1): - self.n += val - self.last_update = time.time() - - @property - def avg(self): - return self.n / self.elapsed_time - - @property - def elapsed_time(self): - return self.init + (time.time() - self.start) - - @property - def u_avg(self): - return self.n / (self.last_update - self.start) - - -class StopwatchMeter(object): - """Computes the sum/avg duration of some event in seconds""" - def __init__(self): - self.reset() - self.intervals = [] - - def start(self): - self.start_time = time.time() - - def stop(self, n=1): - if self.start_time is not None: - delta = time.time() - self.start_time - self.intervals.append(delta) - self.sum += delta - self.n += n - self.start_time = None - - def reset(self): - self.sum = 0 - self.n = 0 - self.start_time = None - self.intervals = [] - - @property - def avg(self): - return self.sum / self.n - - def p(self, i): - assert i <= 100 - idx = int(len(self.intervals) * i / 100) - return sorted(self.intervals)[idx] diff --git a/PyTorch/NLP/Transformer/fairseq/models/__init__.py b/PyTorch/NLP/Transformer/fairseq/models/__init__.py deleted file mode 100644 index d46c163b..00000000 --- a/PyTorch/NLP/Transformer/fairseq/models/__init__.py +++ /dev/null @@ -1,55 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import importlib -import os - -from .fairseq_incremental_decoder import FairseqIncrementalDecoder # noqa: F401 - -MODEL_REGISTRY = {} -ARCH_MODEL_REGISTRY = {} -ARCH_CONFIG_REGISTRY = {} - - -def build_model(args): - return ARCH_MODEL_REGISTRY[args.arch].build_model(args) - - -def register_model(name): - """Decorator to register a new model (e.g., LSTM).""" - - def register_model_cls(cls): - if name in MODEL_REGISTRY: - raise ValueError('Cannot register duplicate model ({})'.format(name)) - MODEL_REGISTRY[name] = cls - return cls - - return register_model_cls - - -def register_model_architecture(model_name, arch_name): - """Decorator to register a new model architecture (e.g., lstm_luong_wmt_en_de).""" - - def register_model_arch_fn(fn): - if model_name not in MODEL_REGISTRY: - raise ValueError('Cannot register model architecture for unknown model type ({})'.format(model_name)) - if arch_name in ARCH_MODEL_REGISTRY: - raise ValueError('Cannot register duplicate model architecture ({})'.format(arch_name)) - if not callable(fn): - raise ValueError('Model architecture must be callable ({})'.format(arch_name)) - ARCH_MODEL_REGISTRY[arch_name] = MODEL_REGISTRY[model_name] - ARCH_CONFIG_REGISTRY[arch_name] = fn - return fn - - return register_model_arch_fn - - -# automatically import any Python files in the models/ directory -for file in os.listdir(os.path.dirname(__file__)): - if file.endswith('.py') and not file.startswith('_'): - module = file[:file.find('.py')] - importlib.import_module('fairseq.models.' + module) diff --git a/PyTorch/NLP/Transformer/fairseq/models/fairseq_incremental_decoder.py b/PyTorch/NLP/Transformer/fairseq/models/fairseq_incremental_decoder.py deleted file mode 100644 index e34df2a2..00000000 --- a/PyTorch/NLP/Transformer/fairseq/models/fairseq_incremental_decoder.py +++ /dev/null @@ -1,42 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import torch.nn as nn - - -class FairseqIncrementalDecoder(nn.Module): - """Base class for incremental decoders.""" - - def __init__(self): - super().__init__() - - def forward(self, prev_output_tokens, encoder_out, incremental_state=None): - raise NotImplementedError - - def reorder_incremental_state(self, incremental_state, new_order): - """Reorder incremental state. - - This should be called when the order of the input has changed from the - previous time step. A typical use case is beam search, where the input - order changes between time steps based on the selection of beams. - """ - def apply_reorder_incremental_state(module): - if module != self and hasattr(module, 'reorder_incremental_state'): - module.reorder_incremental_state( - incremental_state, - new_order, - ) - self.apply(apply_reorder_incremental_state) - - def set_beam_size(self, beam_size): - """Sets the beam size in the decoder and all children.""" - if getattr(self, '_beam_size', -1) != beam_size: - def apply_set_beam_size(module): - if module != self and hasattr(module, 'set_beam_size'): - module.set_beam_size(beam_size) - self.apply(apply_set_beam_size) - self._beam_size = beam_size diff --git a/PyTorch/NLP/Transformer/fairseq/models/fused_layer_norm.py b/PyTorch/NLP/Transformer/fairseq/models/fused_layer_norm.py deleted file mode 100644 index 458feae0..00000000 --- a/PyTorch/NLP/Transformer/fairseq/models/fused_layer_norm.py +++ /dev/null @@ -1,159 +0,0 @@ -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License.import math - -import math -import torch -import numbers -from torch.nn.parameter import Parameter -from torch.nn import init - -import fused_layer_norm_cuda - -class FusedLayerNormAffineFunction(torch.autograd.Function): - def __init__(self, normalized_shape, eps=1e-6): - self.normalized_shape = normalized_shape - self.eps = eps - - def forward(self, input, weight, bias): - input_ = input.contiguous() - weight_ = weight.contiguous() - bias_ = bias.contiguous() - output, mean, invvar = fused_layer_norm_cuda.forward_affine( - input_, self.normalized_shape, weight_, bias_, self.eps) - self.save_for_backward(input_, weight_, bias_, mean, invvar) - return output - - def backward(self, grad_output): - input_, weight_, bias_, mean, invvar = self.saved_tensors - grad_input = grad_weight = grad_bias = None - grad_input, grad_weight, grad_bias = fused_layer_norm_cuda.backward_affine( - grad_output.contiguous(), mean, invvar, - input_, self.normalized_shape, - weight_, bias_, self.eps) - return grad_input, grad_weight, grad_bias; - -class FusedLayerNormFunction(torch.autograd.Function): - def __init__(self, normalized_shape, eps=1e-6): - self.normalized_shape = normalized_shape - self.eps = eps - - def forward(self, input): - input_ = input.contiguous() - output, mean, invvar = fused_layer_norm_cuda.forward( - input_, self.normalized_shape, self.eps) - self.save_for_backward(input_, mean, invvar) - return output - - def backward(self, grad_output): - input_, mean, invvar = self.saved_tensors - grad_input = None - grad_input = fused_layer_norm_cuda.backward( - grad_output.contiguous(), mean, invvar, - input_, self.normalized_shape, - self.eps) - return grad_input - -def fused_layer_norm_affine(input, normalized_shape, weight, bias, eps=1e-6): - return FusedLayerNormAffineFunction(normalized_shape,eps)(input, weight, bias) - -def fused_layer_norm(input, normalized_shape, eps=1e-6): - return FusedLayerNormFunction(normalized_shape,eps)(input) - -class FusedLayerNorm(torch.nn.Module): - r"""Applies Layer Normalization over a mini-batch of inputs as described in - the paper `Layer Normalization`_ . - - .. math:: - y = \frac{x - \mathrm{E}[x]}{ \sqrt{\mathrm{Var}[x] + \epsilon}} * \gamma + \beta - - The mean and standard-deviation are calculated separately over the last - certain number dimensions which have to be of the shape specified by - :attr:`normalized_shape`. - :math:`\gamma` and :math:`\beta` are learnable affine transform parameters of - :attr:`normalized_shape` if :attr:`elementwise_affine` is ``True``. - - .. note:: - Unlike Batch Normalization and Instance Normalization, which applies - scalar scale and bias for each entire channel/plane with the - :attr:`affine` option, Layer Normalization applies per-element scale and - bias with :attr:`elementwise_affine`. - - This layer uses statistics computed from input data in both training and - evaluation modes. - - Args: - normalized_shape (int or list or torch.Size): input shape from an expected input - of size - - .. math:: - [* \times \text{normalized\_shape}[0] \times \text{normalized\_shape}[1] - \times \ldots \times \text{normalized\_shape}[-1]] - - If a single integer is used, it is treated as a singleton list, and this module will - normalize over the last dimension which is expected to be of that specific size. - eps: a value added to the denominator for numerical stability. Default: 1e-5 - elementwise_affine: a boolean value that when set to ``True``, this module - has learnable per-element affine parameters initialized to ones (for weights) - and zeros (for biases). Default: ``True``. - - Shape: - - Input: :math:`(N, *)` - - Output: :math:`(N, *)` (same shape as input) - - Examples:: - - >>> input = torch.randn(20, 5, 10, 10) - >>> # With Learnable Parameters - >>> m = nn.LayerNorm(input.size()[1:]) - >>> # Without Learnable Parameters - >>> m = nn.LayerNorm(input.size()[1:], elementwise_affine=False) - >>> # Normalize over last two dimensions - >>> m = nn.LayerNorm([10, 10]) - >>> # Normalize over last dimension of size 10 - >>> m = nn.LayerNorm(10) - >>> # Activating the module - >>> output = m(input) - - .. _`Layer Normalization`: https://arxiv.org/abs/1607.06450 - """ - def __init__(self, normalized_shape, eps=1e-5, elementwise_affine=True): - super(FusedLayerNorm, self).__init__() - if isinstance(normalized_shape, numbers.Integral): - normalized_shape = (normalized_shape,) - self.normalized_shape = torch.Size(normalized_shape) - self.eps = eps - self.elementwise_affine = elementwise_affine - if self.elementwise_affine: - self.weight = Parameter(torch.Tensor(*normalized_shape)) - self.bias = Parameter(torch.Tensor(*normalized_shape)) - else: - self.register_parameter('weight', None) - self.register_parameter('bias', None) - self.reset_parameters() - - def reset_parameters(self): - if self.elementwise_affine: - init.ones_(self.weight) - init.zeros_(self.bias) - - def forward(self, input): - if self.elementwise_affine: - return FusedLayerNormAffineFunction(self.normalized_shape,self.eps)( - input, self.weight, self.bias) - else: - return FusedLayerNormFunction(self.normalized_shape,self.eps)( - input) - - def extra_repr(self): - return '{normalized_shape}, eps={eps}, ' \ - 'elementwise_affine={elementwise_affine}'.format(**self.__dict__) diff --git a/PyTorch/NLP/Transformer/fairseq/models/transformer.py b/PyTorch/NLP/Transformer/fairseq/models/transformer.py deleted file mode 100644 index 4181c9e8..00000000 --- a/PyTorch/NLP/Transformer/fairseq/models/transformer.py +++ /dev/null @@ -1,621 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import math - -import torch -import torch.nn as nn -import torch.nn.functional as F -from torch import Tensor -from typing import Optional, Dict - -from fairseq.modules import ( - LearnedPositionalEmbedding, MultiheadAttention, SinusoidalPositionalEmbedding -) - -from . import ( - FairseqIncrementalDecoder, register_model, - register_model_architecture, -) - -from apex.normalization.fused_layer_norm import FusedLayerNorm - -torch.set_printoptions(threshold=500000000, linewidth=1024) - - -@torch.jit.script -def jit_dropout_add(x, residual, prob, is_training): - # type: (Tensor, Tensor, float, bool) -> Tensor - out = F.dropout(x, p=prob, training=is_training) - out = residual + out - return out - - -@torch.jit.script -def jit_relu_dropout(x, prob, is_training): - # type: (Tensor, float, bool) -> Tensor - out = F.threshold(x, 0., 0.) - out = F.dropout(out, p=prob, training=is_training) - return out - - -@register_model('transformer') -class TransformerModel(nn.Module): - - @staticmethod - def add_args(parser): - """Add model-specific arguments to the parser.""" - parser.add_argument('--dropout', type=float, metavar='D', - help='dropout probability') - parser.add_argument('--attention-dropout', type=float, metavar='D', - help='dropout probability for attention weights') - parser.add_argument('--relu-dropout', type=float, metavar='D', - help='dropout probability after ReLU in FFN') - parser.add_argument('--encoder-embed-path', type=str, metavar='STR', - help='path to pre-trained encoder embedding') - parser.add_argument('--encoder-embed-dim', type=int, metavar='N', - help='encoder embedding dimension') - parser.add_argument('--encoder-ffn-embed-dim', type=int, metavar='N', - help='encoder embedding dimension for FFN') - parser.add_argument('--encoder-layers', type=int, metavar='N', - help='num encoder layers') - parser.add_argument('--encoder-attention-heads', type=int, metavar='N', - help='num encoder attention heads') - parser.add_argument('--encoder-normalize-before', action='store_true', - help='apply layernorm before each encoder block') - parser.add_argument('--encoder-learned-pos', action='store_true', - help='use learned positional embeddings in the encoder') - parser.add_argument('--decoder-embed-path', type=str, metavar='STR', - help='path to pre-trained decoder embedding') - parser.add_argument('--decoder-embed-dim', type=int, metavar='N', - help='decoder embedding dimension') - parser.add_argument('--decoder-ffn-embed-dim', type=int, metavar='N', - help='decoder embedding dimension for FFN') - parser.add_argument('--decoder-layers', type=int, metavar='N', - help='num decoder layers') - parser.add_argument('--decoder-attention-heads', type=int, metavar='N', - help='num decoder attention heads') - parser.add_argument('--decoder-learned-pos', action='store_true', - help='use learned positional embeddings in the decoder') - parser.add_argument('--decoder-normalize-before', action='store_true', - help='apply layernorm before each decoder block') - parser.add_argument('--share-decoder-input-output-embed', action='store_true', - help='share decoder input and output embeddings') - parser.add_argument('--share-all-embeddings', action='store_true', - help='share encoder, decoder and output embeddings' - ' (requires shared dictionary and embed dim)') - - def __init__(self, encoder, decoder): - super().__init__() - self._is_generation_fast = False - self.encoder = encoder - self.decoder = decoder - - @classmethod - def build_model(cls, args): - # make sure all arguments are present in older models - base_architecture(args) - - if not hasattr(args, 'max_source_positions'): - args.max_source_positions = 1024 - if not hasattr(args, 'max_target_positions'): - args.max_target_positions = 1024 - - if args.share_all_embeddings: - if args.src_vocab_size != args.tgt_vocab_size: - raise RuntimeError('--share-all-embeddings requires a joined dictionary') - if args.encoder_embed_dim != args.decoder_embed_dim: - raise RuntimeError( - '--share-all-embeddings requires --encoder-embed-dim to match --decoder-embed-dim') - if args.decoder_embed_path and ( - args.decoder_embed_path != args.encoder_embed_path): - raise RuntimeError('--share-all-embeddings not compatible with --decoder-embed-path') - encoder_embed_tokens = Embedding(args.src_vocab_size, args.encoder_embed_dim, args.padding_idx) - decoder_embed_tokens = encoder_embed_tokens - args.share_decoder_input_output_embed = True - else: - encoder_embed_tokens = Embedding(args.src_vocab_size, args.encoder_embed_dim, args.padding_idx) - decoder_embed_tokens = Embedding(args.tgt_vocab_size, args.decoder_embed_dim, args.padding_idx) - - encoder = TransformerEncoder(args, encoder_embed_tokens) - decoder = TransformerDecoder(args, decoder_embed_tokens) - - return TransformerModel(encoder, decoder) - - def make_generation_fast_(self, **kwargs): - """Optimize model for faster generation.""" - if self._is_generation_fast: - return # only apply once - self._is_generation_fast = True - - # remove weight norm from all modules in the network - def apply_remove_weight_norm(module): - try: - nn.utils.remove_weight_norm(module) - except ValueError: # this module didn't have weight norm - return - - self.apply(apply_remove_weight_norm) - - def apply_make_generation_fast_(module): - if module != self and hasattr(module, 'make_generation_fast_'): - module.make_generation_fast_(**kwargs) - - self.apply(apply_make_generation_fast_) - - def train(mode): - if mode: - raise RuntimeError('cannot train after make_generation_fast') - - # this model should no longer be used for training - self.eval() - self.train = train - - def forward(self, src_tokens, src_lengths, prev_output_tokens): - encoder_out, padding_mask = self.encoder(src_tokens, src_lengths) - decoder_out = self.decoder(prev_output_tokens, encoder_out, padding_mask) - return decoder_out - - -class TransformerEncoder(nn.Module): - """Transformer encoder.""" - - def __init__(self, args, embed_tokens, left_pad=True): - super().__init__() - self.dropout = args.dropout - self.fuse_dropout_add = args.fuse_dropout_add - self.fuse_relu_dropout = args.fuse_relu_dropout - - embed_dim = embed_tokens.embedding_dim - self.padding_idx = embed_tokens.padding_idx - self.max_source_positions = args.max_source_positions - - self.embed_tokens = embed_tokens - self.embed_scale = math.sqrt(embed_dim) - self.embed_positions = PositionalEmbedding( - args.max_source_positions, embed_dim, self.padding_idx, - left_pad=left_pad, - learned=args.encoder_learned_pos, - ) if not args.no_token_positional_embeddings else None - - self.layers = nn.ModuleList([]) - self.layers.extend([ - TransformerEncoderLayer(args) - for i in range(args.encoder_layers) - ]) - - self.normalize = args.encoder_normalize_before - if self.normalize: - self.layer_norm = FusedLayerNorm(embed_dim) if args.fuse_layer_norm else nn.LayerNorm(embed_dim) - - def forward(self, src_tokens, src_lengths): - # embed tokens and positions - x = self.embed_scale * self.embed_tokens(src_tokens) - if self.embed_positions is not None: - x += self.embed_positions(src_tokens) - x = F.dropout(x, p=self.dropout, training=self.training) - - # B x T x C -> T x B x C - # The tensor needs to copy transposed because - # fused dropout is not capable of handing strided data - if self.fuse_dropout_add: - x = x.transpose(0, 1).contiguous() - else: - x = x.transpose(0, 1) - - # compute padding mask - encoder_padding_mask = src_tokens.eq(self.padding_idx) - if not encoder_padding_mask.any(): - _encoder_padding_mask = None - else: - _encoder_padding_mask = encoder_padding_mask - - # encoder layers - for layer in self.layers: - x = layer(x, _encoder_padding_mask) - - if self.normalize: - x = self.layer_norm(x) - - return x, encoder_padding_mask # x.shape == T x B x C, encoder_padding_mask.shape == B x T - - def reorder_encoder_out(self, encoder_out, encoder_padding_mask, new_order): - if encoder_out is not None: - encoder_out = encoder_out.index_select(1, new_order) - if encoder_padding_mask is not None: - encoder_padding_mask = encoder_padding_mask.index_select(0, new_order) - return encoder_out, encoder_padding_mask - - -class TransformerDecoder(FairseqIncrementalDecoder): - """Transformer decoder.""" - - def __init__(self, args, embed_tokens, no_encoder_attn=False, left_pad=False): - super().__init__() - self.dropout = args.dropout - self.share_input_output_embed = args.share_decoder_input_output_embed - self.fuse_dropout_add = args.fuse_dropout_add - self.fuse_relu_dropout = args.fuse_relu_dropout - - embed_dim = embed_tokens.embedding_dim - padding_idx = embed_tokens.padding_idx - self.max_target_positions = args.max_target_positions - - self.embed_tokens = embed_tokens - self.embed_scale = math.sqrt(embed_dim) - self.embed_positions = PositionalEmbedding( - args.max_target_positions, embed_dim, padding_idx, - left_pad=left_pad, - learned=args.decoder_learned_pos, - ) if not args.no_token_positional_embeddings else None - - self.layers = nn.ModuleList([]) - self.layers.extend([ - TransformerDecoderLayer(args, no_encoder_attn) - for _ in range(args.decoder_layers) - ]) - - if not self.share_input_output_embed: - self.embed_out = nn.Parameter(torch.Tensor(args.tgt_vocab_size, embed_dim)) - nn.init.normal_(self.embed_out, mean=0, std=embed_dim ** -0.5) - else: - self.embed_out = self.embed_tokens.weight - self.normalize = args.decoder_normalize_before - if self.normalize: - self.layer_norm = FusedLayerNorm(embed_dim) if args.fuse_layer_norm else nn.LayerNorm(embed_dim) - - def forward(self, - prev_output_tokens: Tensor, - encoder_out: Tensor, - encoder_padding_mask: Tensor, - incremental_state: Optional[Dict[str, Dict[str, Tensor]]]=None): - # embed positions - positions = self.embed_positions( - prev_output_tokens, - incremental_state=incremental_state, - ) if self.embed_positions is not None else None - - if incremental_state is not None: - prev_output_tokens = prev_output_tokens[:, -1:] - if positions is not None: - positions = positions[:, -1:] - - # embed tokens and positions - x = self.embed_scale * self.embed_tokens(prev_output_tokens) - if positions is not None: - x += positions - x = F.dropout(x, p=self.dropout, training=self.training) - - # B x T x C -> T x B x C - # The tensor needs to copy transposed because - # fused dropout is not capable of handing strided data - if self.fuse_dropout_add: - x = x.transpose(0, 1).contiguous() - else: - x = x.transpose(0, 1) - attn = None - - # decoder layers - for layer in self.layers: - x, attn = layer( - x, - encoder_out, - encoder_padding_mask if encoder_padding_mask.any() else None, - incremental_state, - ) - - if self.normalize: - x = self.layer_norm(x) - - # T x B x C -> B x T x C - x = x.transpose(0, 1) - - # project back to size of vocabulary - x = F.linear(x, self.embed_out) - - return x, attn - - -class TransformerEncoderLayer(nn.Module): - """Encoder layer block. - - In the original paper each operation (multi-head attention or FFN) is - postprocessed with: dropout -> add residual -> layernorm. - In the tensor2tensor code they suggest that learning is more robust when - preprocessing each layer with layernorm and postprocessing with: - dropout -> add residual. - We default to the approach in the paper, but the tensor2tensor approach can - be enabled by setting `normalize_before=True`. - """ - - def __init__(self, args): - super().__init__() - self.embed_dim = args.encoder_embed_dim - self.self_attn = MultiheadAttention( - self.embed_dim, args.encoder_attention_heads, - dropout=args.attention_dropout, - ) - self.dropout = args.dropout - self.relu_dropout = args.relu_dropout - self.fuse_dropout_add = args.fuse_dropout_add - self.fuse_relu_dropout = args.fuse_relu_dropout - self.normalize_before = args.encoder_normalize_before - self.fc1 = Linear(self.embed_dim, args.encoder_ffn_embed_dim) - self.fc2 = Linear(args.encoder_ffn_embed_dim, self.embed_dim) - self.maybe_ln1 = MaybeLayerNorm(self.embed_dim, self.normalize_before, fuse=args.fuse_layer_norm) - self.maybe_ln2 = MaybeLayerNorm(self.embed_dim, self.normalize_before, fuse=args.fuse_layer_norm) - - def forward(self, x: Tensor, encoder_padding_mask: Optional[Tensor]): - residual = x - - x = self.maybe_ln1(x, before=True) - x, _ = self.self_attn(query=x, key=x, value=x, - mask_future_timesteps=False, - key_padding_mask=encoder_padding_mask, - incremental_state=None, - need_weights=False, - static_kv=False) - - if self.fuse_dropout_add and self.training: - x = jit_dropout_add(x, residual, self.dropout, self.training) - else: - x = F.dropout(x, p=self.dropout, training=self.training) - x = residual + x - x = self.maybe_ln1(x, after=True) - - residual = x - x = self.maybe_ln2(x, before=True) - - if self.fuse_relu_dropout: - x = jit_relu_dropout(self.fc1(x), self.relu_dropout, self.training) - else: - x = F.threshold(self.fc1(x), 0.0, 0.0) - x = F.dropout(x, p=self.relu_dropout, training=self.training) - x = self.fc2(x) - - if self.fuse_dropout_add and self.training: - x = jit_dropout_add(x, residual, self.dropout, self.training) - else: - x = F.dropout(x, p=self.dropout, training=self.training) - x = residual + x - x = self.maybe_ln2(x, after=True) - return x - - -class TransformerDecoderLayer(nn.Module): - """Decoder layer block.""" - - def __init__(self, args, no_encoder_attn=False): - super().__init__() - self.embed_dim = args.decoder_embed_dim - self.self_attn = MultiheadAttention( - self.embed_dim, args.decoder_attention_heads, - dropout=args.attention_dropout, - ) - self.dropout = args.dropout - self.relu_dropout = args.relu_dropout - self.normalize_before = args.decoder_normalize_before - self.fuse_dropout_add = args.fuse_dropout_add - self.fuse_relu_dropout = args.fuse_relu_dropout - - self.self_attn_layer_norm = MaybeLayerNorm( - self.embed_dim, self.normalize_before, fuse=args.fuse_layer_norm) - - if no_encoder_attn: - self.encoder_attn = None - self.encoder_attn_layer_norm = None - else: - self.encoder_attn = MultiheadAttention( - self.embed_dim, args.decoder_attention_heads, - dropout=args.attention_dropout, - ) - self.encoder_attn_layer_norm = MaybeLayerNorm( - self.embed_dim, self.normalize_before, fuse=args.fuse_layer_norm) - - self.fc1 = Linear(self.embed_dim, args.decoder_ffn_embed_dim) - self.fc2 = Linear(args.decoder_ffn_embed_dim, self.embed_dim) - - self.final_layer_norm = MaybeLayerNorm( - self.embed_dim, self.normalize_before, fuse=args.fuse_layer_norm) - self.need_attn = True - - def forward(self, - x: Tensor, - encoder_out: Tensor, - encoder_padding_mask: Optional[Tensor], - incremental_state: Optional[Dict[str, Dict[str, Tensor]]]): - residual = x - x = self.self_attn_layer_norm(x, before=True) - x, _ = self.self_attn( - query=x, - key=x, - value=x, - mask_future_timesteps=True, - key_padding_mask=None, - incremental_state=incremental_state, - need_weights=False, - static_kv=False - ) - if self.fuse_dropout_add and self.training: - x = jit_dropout_add(x, residual, self.dropout, self.training) - else: - x = F.dropout(x, p=self.dropout, training=self.training) - x = residual + x - x = self.self_attn_layer_norm(x, after=True) - - attn = None - if self.encoder_attn is not None: - residual = x - x = self.encoder_attn_layer_norm(x, before=True) - x, attn = self.encoder_attn( - query=x, - key=encoder_out, - value=encoder_out, - key_padding_mask=encoder_padding_mask, - incremental_state=incremental_state, - static_kv=True, - mask_future_timesteps=False, - need_weights=(not self.training and self.need_attn), - ) - if self.fuse_dropout_add and self.training: - x = jit_dropout_add(x, residual, self.dropout, self.training) - else: - x = F.dropout(x, p=self.dropout, training=self.training) - x = residual + x - x = self.encoder_attn_layer_norm(x, after=True) - - residual = x - x = self.final_layer_norm(x, before=True) - if self.fuse_relu_dropout: - x = jit_relu_dropout(self.fc1(x), self.relu_dropout, self.training) - else: - x = F.threshold(self.fc1(x), 0.0, 0.0) - x = F.dropout(x, p=self.relu_dropout, training=self.training) - x = self.fc2(x) - if self.fuse_dropout_add and self.training: - x = jit_dropout_add(x, residual, self.dropout, self.training) - else: - x = F.dropout(x, p=self.dropout, training=self.training) - x = residual + x - x = self.final_layer_norm(x, after=True) - return x, attn - - def make_generation_fast_(self, need_attn=False, **kwargs): - self.need_attn = need_attn - - -def Embedding(num_embeddings, embedding_dim, padding_idx): - m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) - nn.init.normal_(m.weight, mean=0, std=embedding_dim ** -0.5) - nn.init.constant_(m.weight[padding_idx], 0) - return m - - -class MaybeLayerNorm(nn.Module): - def __init__(self, embed_dim, normalize_before, fuse=True): - super().__init__() - self.embed_dim = embed_dim - self.normalize_before = normalize_before - self.ln = FusedLayerNorm(embed_dim) if fuse else nn.LayerNorm(embed_dim) - - def forward(self, x: Tensor, before: bool = False, after: bool = False): - assert before ^ after - if after ^ self.normalize_before: - return self.ln(x) - else: - return x - - -def Linear(in_features, out_features, bias=True): - m = nn.Linear(in_features, out_features, bias) - nn.init.xavier_uniform_(m.weight) - nn.init.constant_(m.bias, 0.) - return m - - -def PositionalEmbedding(num_embeddings, embedding_dim, padding_idx, left_pad, learned=False): - if learned: - m = LearnedPositionalEmbedding(num_embeddings + padding_idx + 1, embedding_dim, padding_idx, left_pad) - nn.init.normal_(m.weight, mean=0, std=embedding_dim ** -0.5) - nn.init.constant_(m.weight[padding_idx], 0) - else: - m = SinusoidalPositionalEmbedding( - embedding_dim, padding_idx, left_pad, num_embeddings + padding_idx + 1) - return m - - -@register_model_architecture('transformer', 'transformer') -def base_architecture(args): - args.encoder_embed_path = getattr(args, 'encoder_embed_path', None) - args.encoder_embed_dim = getattr(args, 'encoder_embed_dim', 512) - args.encoder_ffn_embed_dim = getattr(args, 'encoder_ffn_embed_dim', 2048) - args.encoder_layers = getattr(args, 'encoder_layers', 6) - args.encoder_attention_heads = getattr(args, 'encoder_attention_heads', 8) - args.encoder_normalize_before = getattr(args, 'encoder_normalize_before', False) - args.encoder_learned_pos = getattr(args, 'encoder_learned_pos', False) - args.decoder_embed_path = getattr(args, 'decoder_embed_path', None) - args.decoder_embed_dim = getattr(args, 'decoder_embed_dim', args.encoder_embed_dim) - args.decoder_ffn_embed_dim = getattr(args, 'decoder_ffn_embed_dim', args.encoder_ffn_embed_dim) - args.decoder_layers = getattr(args, 'decoder_layers', 6) - args.decoder_attention_heads = getattr(args, 'decoder_attention_heads', 8) - args.decoder_normalize_before = getattr(args, 'decoder_normalize_before', False) - args.decoder_learned_pos = getattr(args, 'decoder_learned_pos', False) - args.attention_dropout = getattr(args, 'attention_dropout', 0.) - args.relu_dropout = getattr(args, 'relu_dropout', 0.) - args.dropout = getattr(args, 'dropout', 0.1) - args.share_decoder_input_output_embed = getattr(args, 'share_decoder_input_output_embed', False) - args.share_all_embeddings = getattr(args, 'share_all_embeddings', False) - args.no_token_positional_embeddings = getattr(args, 'no_token_positional_embeddings', False) - - -@register_model_architecture('transformer', 'transformer_iwslt_de_en') -def transformer_iwslt_de_en(args): - args.encoder_embed_dim = getattr(args, 'encoder_embed_dim', 512) - args.encoder_ffn_embed_dim = getattr(args, 'encoder_ffn_embed_dim', 1024) - args.encoder_attention_heads = getattr(args, 'encoder_attention_heads', 4) - args.encoder_layers = getattr(args, 'encoder_layers', 6) - args.decoder_embed_dim = getattr(args, 'decoder_embed_dim', 512) - args.decoder_ffn_embed_dim = getattr(args, 'decoder_ffn_embed_dim', 1024) - args.decoder_attention_heads = getattr(args, 'decoder_attention_heads', 4) - args.decoder_layers = getattr(args, 'decoder_layers', 6) - base_architecture(args) - - -@register_model_architecture('transformer', 'transformer_wmt_en_de') -def transformer_wmt_en_de(args): - base_architecture(args) - - -# parameters used in the "Attention Is All You Need" paper (Vaswani, et al, 2017) -@register_model_architecture('transformer', 'transformer_vaswani_wmt_en_de_big') -def transformer_vaswani_wmt_en_de_big(args): - args.encoder_embed_dim = getattr(args, 'encoder_embed_dim', 1024) - args.encoder_ffn_embed_dim = getattr(args, 'encoder_ffn_embed_dim', 4096) - args.encoder_attention_heads = getattr(args, 'encoder_attention_heads', 16) - args.encoder_normalize_before = getattr(args, 'encoder_normalize_before', False) - args.decoder_embed_dim = getattr(args, 'decoder_embed_dim', 1024) - args.decoder_ffn_embed_dim = getattr(args, 'decoder_ffn_embed_dim', 4096) - args.decoder_attention_heads = getattr(args, 'decoder_attention_heads', 16) - args.dropout = getattr(args, 'dropout', 0.3) - base_architecture(args) - - -@register_model_architecture('transformer', 'transformer_vaswani_wmt_en_fr_big') -def transformer_vaswani_wmt_en_fr_big(args): - args.dropout = getattr(args, 'dropout', 0.1) - transformer_vaswani_wmt_en_de_big(args) - - -@register_model_architecture('transformer', 'transformer_wmt_en_de_big') -def transformer_wmt_en_de_big(args): - args.attention_dropout = getattr(args, 'attention_dropout', 0.1) - transformer_vaswani_wmt_en_de_big(args) - - -# default parameters used in tensor2tensor implementation -@register_model_architecture('transformer', 'transformer_wmt_en_de_big_t2t') -def transformer_wmt_en_de_big_t2t(args): - args.encoder_normalize_before = getattr(args, 'encoder_normalize_before', True) - args.decoder_normalize_before = getattr(args, 'decoder_normalize_before', True) - args.attention_dropout = getattr(args, 'attention_dropout', 0.1) - args.relu_dropout = getattr(args, 'relu_dropout', 0.1) - transformer_vaswani_wmt_en_de_big(args) diff --git a/PyTorch/NLP/Transformer/fairseq/modules/__init__.py b/PyTorch/NLP/Transformer/fairseq/modules/__init__.py deleted file mode 100644 index 1e23e0d7..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/__init__.py +++ /dev/null @@ -1,18 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -from .beamable_mm import BeamableMM -from .learned_positional_embedding import LearnedPositionalEmbedding -from .multihead_attention import MultiheadAttention -from .sinusoidal_positional_embedding import SinusoidalPositionalEmbedding - -__all__ = [ - 'BeamableMM', - 'LearnedPositionalEmbedding', - 'MultiheadAttention', - 'SinusoidalPositionalEmbedding', -] diff --git a/PyTorch/NLP/Transformer/fairseq/modules/adaptive_softmax.py b/PyTorch/NLP/Transformer/fairseq/modules/adaptive_softmax.py deleted file mode 100644 index aeceb486..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/adaptive_softmax.py +++ /dev/null @@ -1,138 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - - -import torch.nn.functional as F -from torch import nn - - -class AdaptiveSoftmax(nn.Module): - """ - This is an implementation of the efficient softmax approximation for - graphical processing units (GPU), described in the paper "Efficient softmax - approximation for GPUs" (http://arxiv.org/abs/1609.04309). - """ - - def __init__(self, vocab_size, input_dim, cutoff, dropout): - super().__init__() - - if vocab_size > cutoff[-1]: - cutoff = cutoff + [vocab_size] - else: - assert vocab_size == cutoff[ - -1], 'cannot specify cutoff smaller than vocab size' - - output_dim = cutoff[0] + len(cutoff) - 1 - - self.vocab_size = vocab_size - self.cutoff = cutoff - self.dropout = dropout - - self.lsm = nn.LogSoftmax(dim=1) - self.head = nn.Linear(input_dim, output_dim, bias=False) - self.tail = nn.ModuleList() - - for i in range(len(cutoff) - 1): - self.tail.append( - nn.Sequential( - nn.Linear(input_dim, input_dim // 4 ** i, bias=False), - nn.Dropout(dropout), - nn.Linear(input_dim // 4 ** i, cutoff[i + 1] - cutoff[i], bias=False) - ) - ) - - def init_weights(m): - if hasattr(m, 'weight'): - nn.init.xavier_uniform_(m.weight) - - self.apply(init_weights) - - def adapt_target(self, target): - """ - In order to be efficient, the AdaptiveSoftMax does not compute the - scores for all the word of the vocabulary for all the examples. It is - thus necessary to call the method adapt_target of the AdaptiveSoftMax - layer inside each forward pass. - """ - - target = target.view(-1) - new_target = [target.clone()] - target_idxs = [] - - for i in range(len(self.cutoff) - 1): - mask = target.ge(self.cutoff[i]).mul(target.lt(self.cutoff[i + 1])) - new_target[0][mask] = self.cutoff[0] + i - 1 - - if mask.any(): - target_idxs.append(mask.nonzero().squeeze(1)) - new_target.append(target[mask].add(-self.cutoff[i])) - else: - target_idxs.append(None) - new_target.append(None) - - return new_target, target_idxs - - def forward(self, input, target): - """ - Args: - input: (b x t x d) - target: (b x t) - Returns: - 2 lists: output for each cutoff section and new targets by cut off - """ - - input = input.contiguous().view(-1, input.size(-1)) - input = F.dropout(input, p=self.dropout, training=self.training) - - new_target, target_idxs = self.adapt_target(target) - output = [self.head(input)] - - for i in range(len(target_idxs)): - if target_idxs[i] is not None: - output.append(self.tail[i](input.index_select(0, target_idxs[i]))) - else: - output.append(None) - - return output, new_target - - def get_log_prob(self, input, target): - """ - Computes the log probabilities for all the words of the vocabulary, - given a 2D tensor of hidden vectors. - """ - - bsz, length, dim = input.size() - input = input.contiguous().view(-1, dim) - - if target is not None: - _, target_idxs = self.adapt_target(target) - else: - target_idxs = None - - head_y = self.head(input) - log_probs = head_y.new_zeros(input.size(0), self.vocab_size) - - head_sz = self.cutoff[0] + len(self.tail) - log_probs[:, :head_sz] = self.lsm(head_y) - tail_priors = log_probs[:, self.cutoff[0] - 1: head_sz - 1].clone() - - for i in range(len(self.tail)): - start = self.cutoff[i] - end = self.cutoff[i + 1] - - if target_idxs is None: - tail_out = log_probs[:, start:end] - tail_out.copy_(self.tail[i](input)) - log_probs[:, start:end] = self.lsm(tail_out).add_(tail_priors[:, i, None]) - elif target_idxs[i] is not None: - idxs = target_idxs[i] - tail_out = log_probs[idxs, start:end] - tail_out.copy_(self.tail[i](input[idxs])) - log_probs[idxs, start:end] = self.lsm(tail_out).add_(tail_priors[idxs, i, None]) - - log_probs = log_probs.view(bsz, length, -1) - return log_probs diff --git a/PyTorch/NLP/Transformer/fairseq/modules/conv_tbc.py b/PyTorch/NLP/Transformer/fairseq/modules/conv_tbc.py deleted file mode 100644 index a324c206..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/conv_tbc.py +++ /dev/null @@ -1,38 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import torch -from torch.nn.modules.utils import _single - - -class ConvTBC(torch.nn.Module): - """1D convolution over an input of shape (time x batch x channel) - - The implementation uses gemm to perform the convolution. This implementation - is faster than cuDNN for small kernel sizes. - """ - def __init__(self, in_channels, out_channels, kernel_size, padding=0): - super(ConvTBC, self).__init__() - self.in_channels = in_channels - self.out_channels = out_channels - self.kernel_size = _single(kernel_size) - self.padding = _single(padding) - - self.weight = torch.nn.Parameter(torch.Tensor( - self.kernel_size[0], in_channels, out_channels)) - self.bias = torch.nn.Parameter(torch.Tensor(out_channels)) - - def forward(self, input): - return input.contiguous().conv_tbc(self.weight, self.bias, self.padding[0]) - - def __repr__(self): - s = ('{name}({in_channels}, {out_channels}, kernel_size={kernel_size}' - ', padding={padding}') - if self.bias is None: - s += ', bias=False' - s += ')' - return s.format(name=self.__class__.__name__, **self.__dict__) diff --git a/PyTorch/NLP/Transformer/fairseq/modules/grad_multiply.py b/PyTorch/NLP/Transformer/fairseq/modules/grad_multiply.py deleted file mode 100644 index dc524981..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/grad_multiply.py +++ /dev/null @@ -1,20 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import torch - - -class GradMultiply(torch.autograd.Function): - @staticmethod - def forward(ctx, x, scale): - ctx.scale = scale - res = x.new(x) - return res - - @staticmethod - def backward(ctx, grad): - return grad * ctx.scale, None diff --git a/PyTorch/NLP/Transformer/fairseq/modules/learned_positional_embedding.py b/PyTorch/NLP/Transformer/fairseq/modules/learned_positional_embedding.py deleted file mode 100644 index a39a965e..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/learned_positional_embedding.py +++ /dev/null @@ -1,31 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import torch.nn as nn - -from fairseq import utils - - -class LearnedPositionalEmbedding(nn.Embedding): - """This module learns positional embeddings up to a fixed maximum size. - - Padding symbols are ignored, but it is necessary to specify whether padding - is added on the left side (left_pad=True) or right side (left_pad=False). - """ - - def __init__(self, num_embeddings, embedding_dim, padding_idx, left_pad): - super().__init__(num_embeddings, embedding_dim, padding_idx) - self.left_pad = left_pad - - def forward(self, input, incremental_state=None): - """Input is expected to be of size [bsz x seqlen].""" - if incremental_state is not None: - # positions is the same for every token when decoding a single step - positions = input.data.new(1, 1).fill_(self.padding_idx + input.size(1)) - else: - positions = utils.make_positions(input.data, self.padding_idx, self.left_pad) - return super().forward(positions) diff --git a/PyTorch/NLP/Transformer/fairseq/modules/multihead_attention.py b/PyTorch/NLP/Transformer/fairseq/modules/multihead_attention.py deleted file mode 100644 index 935bf507..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/multihead_attention.py +++ /dev/null @@ -1,460 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from typing import Dict, Optional - -import torch -from torch import nn, Tensor -from torch.nn import Parameter -import torch.nn.functional as F -from torch.cuda import amp -from torch.autograd.variable import Variable -import strided_batched_gemm - - -from fairseq import utils - - -class QueryLinear(torch.autograd.Function): - @staticmethod - @amp.custom_fwd(cast_inputs=torch.half) - def forward(ctx, input, weights_q, scale): - s = Variable(torch.tensor([scale])) - ctx.save_for_backward(input, weights_q, s) - q = torch.addmm(input.view(input.size(0) * input.size(1), input.size(2)), - input.view(input.size(0) * input.size(1), input.size(2)), - weights_q, beta=0.0, alpha=s[0]) - q = q.view(input.size(0), input.size(1), input.size(2)) - return q.detach() - - @staticmethod - @amp.custom_bwd - def backward(ctx, q_grad): - input, weights_q, s = ctx.saved_tensors - input = input.view(input.size(0) * input.size(1), input.size(2)).transpose(0, 1) - q = torch.addmm(q_grad.view(q_grad.size(0) * q_grad.size(1), q_grad.size(2)), - q_grad.view(q_grad.size(0) * q_grad.size(1), q_grad.size(2)), - weights_q.transpose(0, 1), beta=0.0, alpha=s[0]) - q = q.view(q_grad.size(0), q_grad.size(1), q_grad.size(2)) - q_grad = q_grad.view(q_grad.size(0) * q_grad.size(1), q_grad.size(2)) - weights_q_grad = torch.addmm(weights_q, input, q_grad, beta=0.0, alpha=s[0]) - return q, weights_q_grad, None - - -class KeyValueLinears(torch.autograd.Function): - @staticmethod - @amp.custom_fwd(cast_inputs=torch.half) - def forward(ctx, input, weights_k, weights_v): - ctx.save_for_backward(input, weights_k, weights_v) - k = torch.addmm(input.view(input.size(0) * input.size(1), input.size(2)), - input.view(input.size(0) * input.size(1), input.size(2)), - weights_k, beta=0.0, alpha=1.0) - k = k.view(input.size(0), input.size(1), input.size(2)) - v = torch.addmm(input.view(input.size(0) * input.size(1), input.size(2)), - input.view(input.size(0) * input.size(1), input.size(2)), - weights_v, beta=0.0, alpha=1.0) - v = v.view(input.size(0), input.size(1), input.size(2)) - return k.detach(), v.detach() - - @staticmethod - @amp.custom_bwd - def backward(ctx, k_grad, v_grad): - input, weights_k, weights_v = ctx.saved_tensors - input = input.view(input.size(0) * input.size(1), input.size(2)).transpose(0, 1) - k = torch.addmm(k_grad.view(k_grad.size(0) * k_grad.size(1), k_grad.size(2)), - k_grad.view(k_grad.size(0) * k_grad.size(1), k_grad.size(2)), - weights_k.transpose(0, 1), beta=0.0) - k_grad = k_grad.view(k_grad.size(0) * k_grad.size(1), k_grad.size(2)) - weights_k_grad = torch.mm(input, k_grad) - v = k.addmm_(v_grad.view(v_grad.size(0) * v_grad.size(1), v_grad.size(2)), - weights_v.transpose(0, 1), beta=1.0) - v = v.view(v_grad.size(0), v_grad.size(1), v_grad.size(2)) - v_grad = v_grad.view(v_grad.size(0) * v_grad.size(1), v_grad.size(2)) - weights_v_grad = torch.mm(input, v_grad) - return v, weights_k_grad, weights_v_grad - - -class SelfAttentionLinears(torch.autograd.Function): - @staticmethod - @amp.custom_fwd(cast_inputs=torch.half) - def forward(ctx, input, weights_q, weights_k, weights_v, scale): - s = Variable(torch.tensor([scale])) - ctx.save_for_backward(input, weights_q, weights_k, weights_v, s) - q = torch.addmm(input.view(input.size(0) * input.size(1), input.size(2)), - input.view(input.size(0) * input.size(1), input.size(2)), - weights_q, beta=0.0, alpha=s[0]) - q = q.view(input.size(0), input.size(1), input.size(2)) - k = torch.addmm(input.view(input.size(0) * input.size(1), input.size(2)), - input.view(input.size(0) * input.size(1), input.size(2)), - weights_k, beta=0.0, alpha=1.0) - k = k.view(input.size(0), input.size(1), input.size(2)) - v = torch.addmm(input.view(input.size(0) * input.size(1), input.size(2)), - input.view(input.size(0) * input.size(1), input.size(2)), - weights_v, beta=0.0, alpha=1.0) - v = v.view(input.size(0), input.size(1), input.size(2)) - return q.detach(), k.detach(), v.detach() - - @staticmethod - @amp.custom_bwd - def backward(ctx, q_grad, k_grad, v_grad): - input, weights_q, weights_k, weights_v, s = ctx.saved_tensors - input = input.view(input.size(0) * input.size(1), input.size(2)).transpose(0, 1) - q = torch.addmm(q_grad.view(q_grad.size(0) * q_grad.size(1), q_grad.size(2)), - q_grad.view(q_grad.size(0) * q_grad.size(1), q_grad.size(2)), - weights_q.transpose(0, 1), beta=0.0, alpha=s[0]) - q_grad = q_grad.view(q_grad.size(0) * q_grad.size(1), q_grad.size(2)) - weights_q_grad = torch.addmm(weights_q, input, q_grad, beta=0.0, alpha=s[0]) - k = q.addmm_(k_grad.view(k_grad.size(0) * k_grad.size(1), k_grad.size(2)), - weights_k.transpose(0, 1), beta=1.0) - k_grad = k_grad.view(k_grad.size(0) * k_grad.size(1), k_grad.size(2)) - weights_k_grad = torch.mm(input, k_grad) - v = k.addmm_(v_grad.view(v_grad.size(0) * v_grad.size(1), v_grad.size(2)), - weights_v.transpose(0, 1), beta=1.0) - v = v.view(v_grad.size(0), v_grad.size(1), v_grad.size(2)) - v_grad = v_grad.view(v_grad.size(0) * v_grad.size(1), v_grad.size(2)) - weights_v_grad = torch.mm(input, v_grad) - return v, weights_q_grad, weights_k_grad, weights_v_grad, None - - -class StridedBmm1Func(torch.autograd.Function): - @staticmethod - @amp.custom_fwd(cast_inputs=torch.half) - def forward(ctx, input1, input2): - ctx.save_for_backward(input1, input2) - output = torch.empty((input1.size(0), input1.size(1), input2.size(2)), - dtype=input1.dtype, device=torch.device('cuda')) - if (input1.dtype == torch.float16) and (input2.dtype == torch.float16): - output = strided_batched_gemm.strided_batched_gemm(0.0, output, 1.0, input1, input2) - else: - output = torch.bmm(input1, input2, out=output) - return output.detach() - - @staticmethod - @amp.custom_bwd - def backward(ctx, grad_output): - input1, input2 = ctx.saved_tensors - grad_input1 = torch.empty((input1.size(1), input2.size(0), input1.size(2)), - dtype=input1.dtype, device=torch.device('cuda')).transpose(1, 0) - grad_input2 = torch.empty((input2.size(2), input2.size(0), input2.size(1)), - dtype=input2.dtype, device=torch.device('cuda')).transpose(1, 0) - if (grad_output.dtype == torch.float16) and (input1.dtype == torch.float16) and (input2.dtype == torch.float16): - grad_input1 = strided_batched_gemm.strided_batched_gemm(0.0, grad_input1, - 1.0, grad_output, - input2.transpose(1, 2)) - grad_input2 = strided_batched_gemm.strided_batched_gemm(0.0, grad_input2, - 1.0, grad_output.transpose(1, 2), - input1) - grad_input2 = grad_input2.transpose(1, 2) - else: - grad_input1 = torch.bmm(grad_output, input2.transpose(1, 2), out=grad_input1) - grad_input2 = torch.bmm(grad_output.transpose(1, 2), input1, out=grad_input2).transpose(1, 2) - return grad_input1, grad_input2 - - -class StridedBmm2Func(torch.autograd.Function): - @staticmethod - @amp.custom_fwd(cast_inputs=torch.half) - def forward(ctx, input1, input2): - ctx.save_for_backward(input1, input2) - output = torch.empty((input1.size(1), input1.size(0), input2.size(2)), - dtype=input1.dtype, device=torch.device('cuda')).transpose(1, 0) - if (input1.dtype == torch.float16) and (input2.dtype == torch.float16): - output = strided_batched_gemm.strided_batched_gemm(0.0, output, 1.0, input1, input2) - else: - output = torch.bmm(input1, input2, out=output) - return output.detach() - - @staticmethod - @amp.custom_bwd - def backward(ctx, grad_output): - input1, input2 = ctx.saved_tensors - grad_input2 = torch.empty((input2.size(1), input2.size(0), input2.size(2)), - dtype=input2.dtype, device=torch.device('cuda')).transpose(1, 0) - grad_input1 = torch.empty((input1.size(0), input1.size(1), input1.size(2)), - dtype=input2.dtype, device=torch.device('cuda')) - if (grad_output.dtype == torch.float16) and (input1.dtype == torch.float16) and (input2.dtype == torch.float16): - grad_input1 = strided_batched_gemm.strided_batched_gemm(0.0, grad_input1, - 1.0, grad_output, - input2.transpose(1, 2)) - grad_input2 = strided_batched_gemm.strided_batched_gemm(0.0, grad_input2, - 1.0, input1.transpose(1, 2), - grad_output) - else: - grad_input1 = torch.bmm(grad_output, input2.transpose(1, 2)) - grad_input2 = torch.bmm(input1.transpose(1, 2), grad_output, out=grad_input2) - return grad_input1, grad_input2 - - -def query_linear(input: Tensor, weights_q: Tensor, scale: float): - if not torch.jit.is_scripting(): - return QueryLinear.apply(input, weights_q, scale) - else: - q = scale * torch.einsum('ij,jk->ik', input.view(input.size(0) * input.size(1), -1), weights_q) - q = q.view(input.shape) - return q - - -def key_value_linears(input: Tensor, weights_k: Tensor, weights_v: Tensor): - if not torch.jit.is_scripting(): - return KeyValueLinears.apply(input, weights_k, weights_v) - else: - k = torch.einsum('ij,jk->ik', input.view(input.size(0) * input.size(1), -1), weights_k) - k = k.view(input.shape) - v = torch.einsum('ij,jk->ik', input.view(input.size(0) * input.size(1), -1), weights_v) - v = v.view(input.shape) - return k, v - - -def self_attn_linears(input: Tensor, weights_q: Tensor, weights_k: Tensor, weights_v: Tensor, scale: float): - if not torch.jit.is_scripting(): - return SelfAttentionLinears.apply(input, weights_q, weights_k, weights_v, scale) - else: - q = scale * torch.einsum('ij,jk->ik', input.view(input.size(0) * input.size(1), -1), weights_q) - q = q.view(input.shape) - k = torch.einsum('ij,jk->ik', input.view(input.size(0) * input.size(1), -1), weights_k) - k = k.view(input.shape) - v = torch.einsum('ij,jk->ik', input.view(input.size(0) * input.size(1), -1), weights_v) - v = v.view(input.shape) - return q, k, v - - -def strided_bmm1(input1: Tensor, input2: Tensor): - if not torch.jit.is_scripting(): - return StridedBmm1Func.apply(input1, input2) - else: - return torch.einsum('ijk,ikn->ijn', input1, input2) - - -def strided_bmm2(input1: Tensor, input2: Tensor): - if not torch.jit.is_scripting(): - return StridedBmm2Func.apply(input1, input2) - else: - return torch.einsum('ijk,ikn->ijn', input1, input2) - - -class MultiheadAttention(nn.Module): - """Multi-headed attention. - - See "Attention Is All You Need" for more details. - """ - def __init__(self, embed_dim, num_heads, dropout=0., bias=False): - super().__init__() - self.embed_dim = embed_dim - self.num_heads = num_heads - self.dropout = dropout - self.head_dim = embed_dim // num_heads - assert self.head_dim * num_heads == self.embed_dim, "embed_dim must be divisible by num_heads" - self.scaling = self.head_dim**-0.5 - self._mask = torch.empty(0) - #self.in_proj_weight = Parameter(torch.Tensor(3*embed_dim, embed_dim)) - self.in_proj_weight_q = Parameter(torch.Tensor(embed_dim, embed_dim)) - self.in_proj_weight_k = Parameter(torch.Tensor(embed_dim, embed_dim)) - self.in_proj_weight_v = Parameter(torch.Tensor(embed_dim, embed_dim)) - if bias: - #self.in_proj_bias = Parameter(torch.Tensor(3*embed_dim)) - self.in_proj_bias_q = Parameter(torch.Tensor(embed_dim)) - self.in_proj_bias_k = Parameter(torch.Tensor(embed_dim)) - self.in_proj_bias_v = Parameter(torch.Tensor(embed_dim)) - else: - #self.register_parameter('in_proj_bias', None) - self.register_parameter('in_proj_bias_k', None) - self.register_parameter('in_proj_bias_q', None) - self.register_parameter('in_proj_bias_v', None) - - self.out_proj = nn.Linear(embed_dim, embed_dim, bias=bias) - self.cache_id = str(id(self)) - - self.reset_parameters() - - def reset_parameters(self): - #nn.init.xavier_uniform_(self.in_proj_weight) - nn.init.xavier_uniform_(self.in_proj_weight_q) - nn.init.xavier_uniform_(self.in_proj_weight_k) - nn.init.xavier_uniform_(self.in_proj_weight_v) - nn.init.xavier_uniform_(self.out_proj.weight) - if self.in_proj_bias_k is not None: - #nn.init.constant_(self.in_proj_bias, 0.) - nn.init.constant_(self.in_proj_bias_q, 0.) - nn.init.constant_(self.in_proj_bias_k, 0.) - nn.init.constant_(self.in_proj_bias_v, 0.) - nn.init.constant_(self.out_proj.bias, 0.) - - def forward(self, query: Tensor, key: Tensor, value: Tensor, - mask_future_timesteps: bool, - key_padding_mask: Optional[Tensor], - incremental_state: Optional[Dict[str, Dict[str, Tensor]]], - need_weights: bool, - static_kv: bool): - """Input shape: Time x Batch x Channel - - Self-attention can be implemented by passing in the same arguments for - query, key and value. Future timesteps can be masked with the - `mask_future_timesteps` argument. Padding elements can be excluded from - the key by passing a binary ByteTensor (`key_padding_mask`) with shape: - batch x src_len, where padding elements are indicated by 1s. - """ - - if torch.jit.is_scripting(): - kv_same = torch.equal(key, value) - qkv_same = torch.equal(query, value) and kv_same - else: - qkv_same, kv_same = self._fast_same_check(query, key, value) - - tgt_len, bsz, embed_dim = query.size() - assert embed_dim == self.embed_dim - assert list(query.size()) == [tgt_len, bsz, embed_dim] - assert key.size() == value.size() - - k = v = query.new_empty(0) - if incremental_state is not None: - saved_state = self._get_input_buffer(incremental_state) - else: - saved_state = None - - if qkv_same: - # self-attention - q, k, v = self_attn_linears(query, self.in_proj_weight_q, - self.in_proj_weight_k, self.in_proj_weight_v, self.scaling) - elif kv_same: - # encoder-decoder attention - q = query_linear(query, self.in_proj_weight_q, self.scaling) - if not(saved_state is not None and 'prev_key' in saved_state and static_kv): - k, v = key_value_linears(key, self.in_proj_weight_k, self.in_proj_weight_v) - else: - q = torch.addmm(query.view(query.size(0) * query.size(1), - query.size(2)), query.view(query.size(0) * query.size(1), - query.size(2)), self.in_proj_weight_q, beta=0.0, alpha=self.scaling) - if not(saved_state is not None and 'prev_key' in saved_state and static_kv): - k = F.linear(key, self.in_proj_weight_k, self.in_proj_bias_k) - v = F.linear(value, self.in_proj_weight_v, self.in_proj_bias_v) - - if saved_state is not None: - if 'prev_key' in saved_state: - k = torch.cat((saved_state['prev_key'], k), dim=0) - if 'prev_value' in saved_state: - v = torch.cat((saved_state['prev_value'], v), dim=0) - saved_state['prev_key'] = k - saved_state['prev_value'] = v - self._set_input_buffer(incremental_state, saved_state) - - src_len = k.size(0) - - if key_padding_mask is not None: - assert key_padding_mask.size(0) == bsz - assert key_padding_mask.size(1) == src_len - - q = q.contiguous().view(tgt_len, bsz * self.num_heads, self.head_dim).transpose(0, 1) - k = k.contiguous().view(src_len, bsz * self.num_heads, self.head_dim).transpose(0, 1) - v = v.contiguous().view(src_len, bsz * self.num_heads, self.head_dim).transpose(0, 1) - - attn_weights = strided_bmm1(q, k.transpose(1, 2)) - assert list(attn_weights.size()) == [bsz * self.num_heads, tgt_len, src_len] - - # only apply masking at training time (when incremental state is None) - if mask_future_timesteps and incremental_state is None: - assert query.size() == key.size(), \ - 'mask_future_timesteps only applies to self-attention' - attn_weights += self.buffered_mask(attn_weights).unsqueeze(0) - if key_padding_mask is not None: - # don't attend to padding symbols - attn_weights = attn_weights.view(bsz, self.num_heads, tgt_len, src_len) - attn_weights = attn_weights.float().masked_fill( - key_padding_mask.unsqueeze(1).unsqueeze(2), - float('-inf'), - ).type_as(attn_weights) # FP16 support: cast to float and back - attn_weights = attn_weights.view(bsz * self.num_heads, tgt_len, src_len) - attn_weights = F.softmax(attn_weights, dim=-1) - attn_weights = F.dropout(attn_weights, p=self.dropout, training=self.training) - attn = strided_bmm2(attn_weights, v) - assert list(attn.size()) == [bsz * self.num_heads, tgt_len, self.head_dim] - attn = attn.transpose(0, 1).contiguous().view(tgt_len, bsz, embed_dim) - attn = self.out_proj(attn) - - if need_weights: - # average attention weights over heads - attn_weights = attn_weights.view(bsz, self.num_heads, tgt_len, src_len) - attn_weights = attn_weights.sum(dim=1) / self.num_heads - else: - attn_weights = attn_weights.new_empty(0) # Can't set to None because jit script reasons - - return attn, attn_weights - - def in_proj_qkv(self, query): - return self._in_proj(query).chunk(3, dim=-1) - - def in_proj_kv(self, key): - return self._in_proj(key, start=self.embed_dim).chunk(2, dim=-1) - - def in_proj_q(self, query): - return self._in_proj(query, end=self.embed_dim) - - def in_proj_k(self, key): - return self._in_proj(key, start=self.embed_dim, end=2 * self.embed_dim) - - def in_proj_v(self, value): - return self._in_proj(value, start=2 * self.embed_dim) - - def _in_proj(self, input, start=None, end=None): - weight = self.in_proj_weight - bias = self.in_proj_bias - if end is not None: - weight = weight[:end, :] - if bias is not None: - bias = bias[:end] - if start is not None: - weight = weight[start:, :] - if bias is not None: - bias = bias[start:] - return F.linear(input, weight, bias) - - def buffered_mask(self, tensor): - dim = tensor.size(-1) - if self._mask.size(0) == 0: - #TODO: try torch.new_full instead - self._mask = torch.triu(utils.fill_with_neg_inf(tensor.new_empty(dim, dim)), 1) - if self._mask.size(0) < dim: - self._mask = torch.triu(utils.fill_with_neg_inf(self._mask.resize_(dim, dim)), 1) - return self._mask[:dim, :dim] - - def reorder_incremental_state(self, incremental_state, new_order): - """Reorder buffered internal state (for incremental generation).""" - input_buffer = self._get_input_buffer(incremental_state) - if input_buffer is not None: - for k in input_buffer.keys(): - input_buffer[k] = input_buffer[k].index_select(1, new_order) - self._set_input_buffer(incremental_state, input_buffer) - - def _get_input_buffer(self, incremental_state: Optional[Dict[str, Dict[str, Tensor]]]): - if incremental_state is None or self.cache_id not in incremental_state: - return {} - return incremental_state[self.cache_id] - - def _set_input_buffer(self, incremental_state: Optional[Dict[str, Dict[str, Tensor]]], - buffer: Dict[str, Tensor]): - if incremental_state is not None: - incremental_state[self.cache_id] = buffer - - @torch.jit.unused - def _fast_same_check(self, q, k, v): - qkv_same = q.data_ptr() == k.data_ptr() == v.data_ptr() - kv_same = k.data_ptr() == v.data_ptr() - return qkv_same, kv_same diff --git a/PyTorch/NLP/Transformer/fairseq/modules/sinusoidal_positional_embedding.py b/PyTorch/NLP/Transformer/fairseq/modules/sinusoidal_positional_embedding.py deleted file mode 100644 index 38e8baac..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/sinusoidal_positional_embedding.py +++ /dev/null @@ -1,82 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import math -from typing import Optional, Dict - - -import torch -import torch.nn as nn -from torch import Tensor - - -class SinusoidalPositionalEmbedding(nn.Module): - """This module produces sinusoidal positional embeddings of any length. - - Padding symbols are ignored, but it is necessary to specify whether padding - is added on the left side (left_pad=True) or right side (left_pad=False). - """ - - def __init__(self, embedding_dim, padding_idx, left_pad, init_size=1024): - super().__init__() - self.embedding_dim = embedding_dim - self.padding_idx = padding_idx - self.left_pad = left_pad - self.weights = SinusoidalPositionalEmbedding.get_embedding( - init_size, - embedding_dim, - padding_idx, - ) - self.register_buffer('_float_tensor', torch.FloatTensor(1)) - # JIT compliance - self.register_buffer( - 'positions_buffer', torch.arange(padding_idx + 1, init_size + padding_idx + 1)) - - @staticmethod - def get_embedding(num_embeddings: int, embedding_dim: int, padding_idx: int): - """Build sinusoidal embeddings. - - This matches the implementation in tensor2tensor, but differs slightly - from the description in Section 3.5 of "Attention Is All You Need". - """ - half_dim = embedding_dim // 2 - emb = math.log(10000) / (half_dim - 1) - emb = torch.exp(torch.arange(half_dim, dtype=torch.float) * -emb) - emb = torch.arange(num_embeddings, dtype=torch.float).unsqueeze(1) * emb.unsqueeze(0) - emb = torch.cat([torch.sin(emb), torch.cos(emb)], dim=1).view(num_embeddings, -1) - if embedding_dim % 2 == 1: - # zero pad - emb = torch.cat([emb, torch.zeros(num_embeddings, 1)], dim=1) - emb[padding_idx] = torch.zeros(emb.shape[1]) # emb[padding_idx, :] = 0 - return emb - - def forward(self, input: Tensor, incremental_state: Optional[Dict[str, Dict[str, Tensor]]]=None): - """Input is expected to be of size [bsz x seqlen].""" - # recompute/expand embeddings if needed - bsz, seq_len = input.size() - max_pos = self.padding_idx + 1 + seq_len - if self.weights is None or max_pos > self.weights.size(0): - self.weights = SinusoidalPositionalEmbedding.get_embedding( - max_pos, - self.embedding_dim, - self.padding_idx, - ) - self.weights = self.weights.type_as(self._float_tensor) - - if incremental_state is not None: - # positions is the same for every token when decoding a single step - return self.weights[self.padding_idx + seq_len, :].expand(bsz, 1, -1) - - #### JIT #### - mask = input.ne(self.padding_idx) - positions = self.positions_buffer[:input.size(1)].expand_as(input) - if self.left_pad: - positions = positions - mask.size(1) + mask.long().sum(dim=1).unsqueeze(1) - positions = input.clone().masked_scatter_(mask, positions[mask]) - ############# - - return self.weights.index_select(0, positions.view(-1)).view(bsz, seq_len, -1).detach() diff --git a/PyTorch/NLP/Transformer/fairseq/modules/strided_batched_gemm/strided_batched_gemm.cpp b/PyTorch/NLP/Transformer/fairseq/modules/strided_batched_gemm/strided_batched_gemm.cpp deleted file mode 100644 index d27ae38e..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/strided_batched_gemm/strided_batched_gemm.cpp +++ /dev/null @@ -1,61 +0,0 @@ -// Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -#include -#include - -at::Tensor strided_batched_gemm_cuda( - float beta, - at::Tensor in_result, - float alpha, - at::Tensor batch1, - at::Tensor batch2); - -// C++ interface - -#define CHECK_CUDA(x) AT_ASSERTM(x.type().is_cuda(), #x " must be a CUDA tensor") -#define CHECK_CONTIGUOUS(x) AT_ASSERTM(x.is_contiguous(), #x " must be contiguous") -#define CHECK_INPUT(x) CHECK_CUDA(x); CHECK_CONTIGUOUS(x) - -at::Tensor strided_batched_gemm( - float beta, - at::Tensor in_result, - float alpha, - at::Tensor batch1, - at::Tensor batch2) { - //CHECK_INPUT(in_result); - //CHECK_INPUT(batch1); - //CHECK_INPUT(batch2); - - AT_ASSERTM(in_result.dim() == 3, "expected 3D tensor"); - AT_ASSERTM(batch1.dim() == 3, "expected 3D tensor"); - AT_ASSERTM(batch2.dim() == 3, "expected 3D tensor"); - - AT_ASSERTM(in_result.size(0) == batch1.size(0), "equal number of batches expected"); - AT_ASSERTM(in_result.size(0) == batch2.size(0), "equal number of batches expected"); - - AT_ASSERTM(in_result.size(1) == batch1.size(1), "wrong matrix size"); - AT_ASSERTM(in_result.size(2) == batch2.size(2), "wrong matrix size"); - AT_ASSERTM(batch1.size(2) == batch2.size(1), "wrong matrix size"); - - AT_ASSERTM(batch1.type().scalarType() == at::ScalarType::Half, "Only HALF is supported"); - AT_ASSERTM(batch2.type().scalarType() == at::ScalarType::Half, "Only HALF is supported"); - AT_ASSERTM(in_result.type().scalarType() == at::ScalarType::Half, "Only HALF is supported"); - - return strided_batched_gemm_cuda(beta, in_result, alpha, batch1, batch2); -} - -PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) { - m.def("strided_batched_gemm", &strided_batched_gemm, "Special strided batched gemm."); -} - diff --git a/PyTorch/NLP/Transformer/fairseq/modules/strided_batched_gemm/strided_batched_gemm_cuda.cu b/PyTorch/NLP/Transformer/fairseq/modules/strided_batched_gemm/strided_batched_gemm_cuda.cu deleted file mode 100644 index e2859cb2..00000000 --- a/PyTorch/NLP/Transformer/fairseq/modules/strided_batched_gemm/strided_batched_gemm_cuda.cu +++ /dev/null @@ -1,345 +0,0 @@ -// Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -// Licensed under the Apache License, Version 2.0 (the "License"); -// you may not use this file except in compliance with the License. -// You may obtain a copy of the License at -// -// http://www.apache.org/licenses/LICENSE-2.0 -// -// Unless required by applicable law or agreed to in writing, software -// distributed under the License is distributed on an "AS IS" BASIS, -// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -// See the License for the specific language governing permissions and -// limitations under the License. - -#include -#include - -#include -#include -#include -#include -#include - -#include "THC/THC.h" - -#include "cutlass/cutlass.h" -#include "cutlass/gemm/gemm.h" -#include "cutlass/gemm/wmma_gemm_traits.h" - -// symbol to be automatically resolved by PyTorch libs -extern THCState *state; - -cublasOperation_t convertTransToCublasOperation(char trans) { - if (trans == 't') return CUBLAS_OP_T; - else if (trans == 'n') return CUBLAS_OP_N; - else if (trans == 'c') return CUBLAS_OP_C; - else { - THError("trans must be one of: t, n, c"); - return CUBLAS_OP_T; - } -} - -void CublasGemm(THCState *state, char transa, char transb, long m, long n, long k, - float alpha, const half *a, long lda, long strideA, const half *b, long ldb, long strideB, - float beta, half *c, long ldc, long strideC, long batchCount) { - cublasOperation_t opa = convertTransToCublasOperation(transa); - cublasOperation_t opb = convertTransToCublasOperation(transb); - - cublasHandle_t handle = at::cuda::getCurrentCUDABlasHandle(); - //cublasSetStream(handle, THCState_getCurrentStream(state)); - float fAlpha = alpha; - float fBeta = beta; - THCublasCheck(cublasSetMathMode(handle, CUBLAS_TENSOR_OP_MATH)); - THCublasCheck(cublasGemmStridedBatchedEx(handle, - opa, opb, (int)m, (int)n, (int)k, - (void*)&fAlpha, a, CUDA_R_16F, (int)lda, strideA, - b, CUDA_R_16F, (int)ldb, strideB, - (void*)&fBeta, c, CUDA_R_16F, (int)ldc, strideC, - (int)batchCount, CUDA_R_32F, CUBLAS_GEMM_DEFAULT_TENSOR_OP)); - THCublasCheck(cublasSetMathMode(handle, CUBLAS_DEFAULT_MATH)); -} - -template -void CutlassGemm_FP32Accum(cudaStream_t stream, long m, long n, long k, - float alpha, const half *a, long lda, long strideA, const half *b, long ldb, long strideB, - float beta, half *c, long ldc, long strideC, long batchCount) { - //printf("CUTLASS-> %c%c M: %ld N: %ld K: %ld %d%d%d LDA: %ld LDB: %ld LDC: %ld strideA: %ld strideB: %ld strideC: %ld Alpha: %f Beta: %f\n", ((int)A_LAYOUT == 0 ? 'T' : 'N'), ((int)B_LAYOUT ==0 ? 'T' : 'N'), m, n, k, SRC_A,SRC_B,DST_C, lda, ldb, ldc, strideA, strideB, strideC, alpha, beta); - typedef cutlass::gemm::WmmaGemmTraits< - A_LAYOUT, - B_LAYOUT, - cutlass::Shape<32, 16, 16>, - half, - half, - half, - cutlass::gemm::LinearScaling, - float, - typename cutlass::gemm::WmmaGemmAccumulatorsPerWarp >::Shape, - typename cutlass::Shape<16, 16, 16>, - SRC_A, //kScalarsPerLdgA_ - SRC_B, //kScalarsPerLdgB_ - SRC_A, //KScalarsPerLdsA_ - SRC_B, //KScalarsPerLdsB_ - DST_C, //kScalarsPerLdgCAndStgD_ - DST_C/2, //kScalarsPerStsD_ - DST_C/2 //kScalarsPerLdsD_ - > - WmmaGemmTraits; - - typedef cutlass::gemm::Gemm Gemm; - typename Gemm::Params params; - - - int result = params.initialize( - m, // M dimension for each batch - n, // N dimension for each batch - k, // K dimension for each batch - alpha, // scalar alpha - a, - lda, - strideA, // distance in memory between the first element of neighboring batch - b, - ldb, - strideB, // distance in memory between the first element of neighboring batch - beta, // scalar beta - c, // source matrix C - ldc, - strideC, // distance in memory between the first element of neighboring batch - c, // destination matrix C (may be different memory than source C matrix) - ldc, - strideC, // distance in memory between the first element of neighboring batch - batchCount - ); - - AT_ASSERTM(result == 0, "Failed to initialize CUTLASS Gemm::Params object."); - - // Launch the CUTLASS GEMM kernel. - THCudaCheck(Gemm::launch(params)); - -} - -void gemm_switch_fp32accum(THCState *state, char transa, char transb, long m, long n, long k, - float alpha, const half *a, long lda, long strideA, const half *b, long ldb, long strideB, - float beta, half *c, long ldc, long strideC, long batchCount) { - //cudaStream_t stream = THCState_getCurrentStream(state); - //printf("GEMM -> %c%c M: %i N: %i K: %i Alpha: %f Beta: %f\n", (transa == 't' ? 'T' : 'N'), (transb =='t' ? 'T' : 'N'), m, n, k, alpha, beta); - auto stream = c10::cuda::getCurrentCUDAStream(); - if ( (transa == 't') && (transb == 'n') ) { - if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x7)) { CublasGemm(state, transa, transb, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x3) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else { CublasGemm(state, transa, transb, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - } else if ( (transa == 'n') && (transb == 'n') ) { - if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x7)) { CublasGemm(state, transa, transb, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x3) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else { CublasGemm(state, transa, transb, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - } else if ( (transa == 'n') && (transb == 't') ) { - if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x7)) { CublasGemm(state, transa, transb, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x3) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x7) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x3) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x7) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x3) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x7)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x3)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else if (!(lda & 0x1) && !(ldb & 0x1) && !(ldc & 0x1)) { CutlassGemm_FP32Accum(stream, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - else { CublasGemm(state, transa, transb, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); } - } else { - AT_ASSERTM(false, "TransA and TransB are invalid"); - } -} - -void adjustLdLevel3(char transa, char transb, int64_t m, int64_t n, int64_t k, int64_t *lda, int64_t *ldb, int64_t *ldc) -{ - int transa_ = ((transa == 't') || (transa == 'T')); - int transb_ = ((transb == 't') || (transb == 'T')); - - // Note: leading dimensions generally are checked that they are > 0 and at least as big the result - // requires (even if the value won't be used). - if(n <= 1) - *ldc = std::max(m, 1); - - if(transa_) - { - if(m <= 1) - *lda = std::max(k, 1); - } - else - { - if(k <= 1) - *lda = std::max(m, 1); - } - - if(transb_) - { - if(k <= 1) - *ldb = std::max(n, 1); - } - else - { - if(n <= 1) - *ldb = std::max(k, 1); - } - -} - -void HgemmStridedBatched(THCState *state, char transa, char transb, long m, long n, long k, - float alpha, const half *a, long lda, long strideA, const half *b, long ldb, long strideB, - float beta, half *c, long ldc, long strideC, long batchCount) -{ - if( (m >= INT_MAX) || (n >= INT_MAX) || (k >= INT_MAX) || (lda >= INT_MAX) || (ldb >= INT_MAX) || (ldc >= INT_MAX) || (batchCount >= INT_MAX) ) - - { - THError("Cublas_SgemmStridedBatched only supports m, n, k, lda, ldb, ldc, batchCount" - "with the bound [val] <= %d", INT_MAX); - } - - adjustLdLevel3(transa, transb, m, n, k, &lda, &ldb, &ldc); - - //gemm_switch(state, transa, transb, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); - gemm_switch_fp32accum(state, transa, transb, m, n, k, alpha, a, lda, strideA, b, ldb, strideB, beta, c, ldc, strideC, batchCount); -} - -at::Tensor strided_batched_gemm_cuda( - float beta, - at::Tensor in_result, - float alpha, - at::Tensor batch1, - at::Tensor batch2) { - - bool transpose_result; - char transpose_batch1, transpose_batch2; - int64_t lda, ldb, ldc; - at::Tensor result, input1, input2; - if (in_result.stride(1) == 1) - { - transpose_result = false; - result = in_result; - ldc = result.stride(2); - } - else if (in_result.stride(2) == 1) - { - transpose_result = true; - - at::Tensor swap = batch2; - batch2 = batch1; - batch1 = swap; - - result = in_result; - ldc = result.stride(1); - } else { - AT_ASSERTM(false, "result should be contiguous"); - } - - if (batch1.stride(transpose_result ? 2 : 1) == 1 && - batch1.stride(transpose_result ? 1 : 2) != 0) { - transpose_batch1 = 'n'; - input1 = batch1; - lda = input1.stride(transpose_result ? 1 : 2); - } else if (batch1.stride(transpose_result ? 1 : 2) == 1 && - batch1.stride(transpose_result ? 2 : 1) != 0) { - transpose_batch1 = 't'; - input1 = batch1; - lda = input1.stride(transpose_result ? 2 : 1); - } else { - AT_ASSERTM(false, "input1 should be contiguous"); - } - - if (batch2.stride(transpose_result ? 2 : 1) == 1 && - batch2.stride(transpose_result ? 1 : 2) != 0) { - transpose_batch2 = 'n'; - input2 = batch2; - ldb = input2.stride(transpose_result ? 1 : 2); - } else if (batch2.stride(transpose_result ? 1 : 2) == 1 && - batch2.stride(transpose_result ? 2 : 1) != 0) { - transpose_batch2 = 't'; - input2 = batch2; - ldb = input2.stride(transpose_result ? 2 : 1); - } else { - AT_ASSERTM(false, "input2 should be contiguous"); - } - int64_t num_batches = result.size(0); - - HgemmStridedBatched( - state, - transpose_batch1, - transpose_batch2, - result.size(transpose_result ? 2 : 1), - result.size(transpose_result ? 1 : 2), - input1.size(transpose_result ? 1 : 2), - alpha, - static_cast(input1.data_ptr()), lda, input1.stride(0), - static_cast(input2.data_ptr()), ldb, input2.stride(0), - beta, - static_cast(result.data_ptr()), ldc, result.stride(0), - num_batches); - - return in_result; -} - - diff --git a/PyTorch/NLP/Transformer/fairseq/multiprocessing_pdb.py b/PyTorch/NLP/Transformer/fairseq/multiprocessing_pdb.py deleted file mode 100644 index b47fb7f2..00000000 --- a/PyTorch/NLP/Transformer/fairseq/multiprocessing_pdb.py +++ /dev/null @@ -1,39 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import multiprocessing -import os -import pdb -import sys - - -class MultiprocessingPdb(pdb.Pdb): - """A Pdb wrapper that works in a multiprocessing environment. - - Usage: `from fairseq import pdb; pdb.set_trace()` - """ - - _stdin_fd = sys.stdin.fileno() - _stdin = None - _stdin_lock = multiprocessing.Lock() - - def __init__(self): - pdb.Pdb.__init__(self, nosigint=True) - - def _cmdloop(self): - stdin_bak = sys.stdin - with self._stdin_lock: - try: - if not self._stdin: - self._stdin = os.fdopen(self._stdin_fd) - sys.stdin = self._stdin - self.cmdloop() - finally: - sys.stdin = stdin_bak - - -pdb = MultiprocessingPdb() diff --git a/PyTorch/NLP/Transformer/fairseq/optim/__init__.py b/PyTorch/NLP/Transformer/fairseq/optim/__init__.py deleted file mode 100644 index 91934dce..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/__init__.py +++ /dev/null @@ -1,46 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import importlib -import os - -from .fairseq_optimizer import FairseqOptimizer - - -OPTIMIZER_REGISTRY = {} -OPTIMIZER_CLASS_NAMES = set() - - -def build_optimizer(args, params): - params = filter(lambda p: p.requires_grad, params) - return OPTIMIZER_REGISTRY[args.optimizer](args, params) - - -def register_optimizer(name): - """Decorator to register a new optimizer.""" - - def register_optimizer_cls(cls): - if name in OPTIMIZER_REGISTRY: - raise ValueError('Cannot register duplicate optimizer ({})'.format(name)) - if not issubclass(cls, FairseqOptimizer): - raise ValueError('Optimizer ({}: {}) must extend FairseqOptimizer'.format(name, cls.__name__)) - if cls.__name__ in OPTIMIZER_CLASS_NAMES: - # We use the optimizer class name as a unique identifier in - # checkpoints, so all optimizer must have unique class names. - raise ValueError('Cannot register optimizer with duplicate class name ({})'.format(cls.__name__)) - OPTIMIZER_REGISTRY[name] = cls - OPTIMIZER_CLASS_NAMES.add(cls.__name__) - return cls - - return register_optimizer_cls - - -# automatically import any Python files in the optim/ directory -for file in os.listdir(os.path.dirname(__file__)): - if file.endswith('.py') and not file.startswith('_'): - module = file[:file.find('.py')] - importlib.import_module('fairseq.optim.' + module) diff --git a/PyTorch/NLP/Transformer/fairseq/optim/adagrad.py b/PyTorch/NLP/Transformer/fairseq/optim/adagrad.py deleted file mode 100644 index 50f2dea9..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/adagrad.py +++ /dev/null @@ -1,30 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import torch.optim - -from . import FairseqOptimizer, register_optimizer - - -@register_optimizer('adagrad') -class Adagrad(FairseqOptimizer): - def __init__(self, args, params): - super().__init__(args, params) - self._optimizer = torch.optim.Adagrad(params, **self.optimizer_config) - - @property - def optimizer_config(self): - """ - Return a kwarg dictionary that will be used to override optimizer - args stored in checkpoints. This allows us to load a checkpoint and - resume training using a different set of optimizer args, e.g., with a - different learning rate. - """ - return { - 'lr': self.args.lr[0], - 'weight_decay': self.args.weight_decay, - } diff --git a/PyTorch/NLP/Transformer/fairseq/optim/adam.py b/PyTorch/NLP/Transformer/fairseq/optim/adam.py deleted file mode 100644 index e60d0eb1..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/adam.py +++ /dev/null @@ -1,54 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from . import FairseqOptimizer, register_optimizer -from apex.optimizers.fused_adam import FusedAdam - - -@register_optimizer('adam') -class FairseqAdam(FairseqOptimizer): - def __init__(self, args, params): - super().__init__(args, params) - self._optimizer = FusedAdam(params, **self.optimizer_config) - - @staticmethod - def add_args(parser): - """Add optimizer-specific arguments to the parser.""" - parser.add_argument('--adam-betas', default=(0.9, 0.999), nargs=2, type=float, metavar='B1 B2', - help='betas for Adam optimizer') - parser.add_argument('--adam-eps', type=float, default=1e-8, metavar='D', - help='epsilon for Adam optimizer') - - @property - def optimizer_config(self): - """ - Return a kwarg dictionary that will be used to override optimizer - args stored in checkpoints. This allows us to load a checkpoint and - resume training using a different set of optimizer args, e.g., with a - different learning rate. - """ - return { - 'lr': self.args.lr[0], - 'betas': self.args.adam_betas, - 'eps': self.args.adam_eps, - 'weight_decay': self.args.weight_decay, - } diff --git a/PyTorch/NLP/Transformer/fairseq/optim/fairseq_optimizer.py b/PyTorch/NLP/Transformer/fairseq/optim/fairseq_optimizer.py deleted file mode 100644 index d4c0ee4f..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/fairseq_optimizer.py +++ /dev/null @@ -1,94 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import torch.optim - - -class FairseqOptimizer(object): - - def __init__(self, args, params): - super().__init__() - self.args = args - self.params = params - - @staticmethod - def add_args(parser): - """Add optimizer-specific arguments to the parser.""" - pass - - @property - def optimizer(self): - """Return a torch.optim.optimizer.Optimizer instance.""" - if not hasattr(self, '_optimizer'): - raise NotImplementedError - if not isinstance(self._optimizer, torch.optim.Optimizer): - raise ValueError('_optimizer must be an instance of torch.optim.Optimizer') - return self._optimizer - - @property - def optimizer_config(self): - """ - Return a kwarg dictionary that will be used to override optimizer - args stored in checkpoints. This allows us to load a checkpoint and - resume training using a different set of optimizer args, e.g., with a - different learning rate. - """ - raise NotImplementedError - - def get_lr(self): - """Return the current learning rate.""" - return self.optimizer.param_groups[0]['lr'] - - def set_lr(self, lr): - """Set the learning rate.""" - for param_group in self.optimizer.param_groups: - param_group['lr'] = lr - - def state_dict(self): - """Return the optimizer's state dict.""" - return self.optimizer.state_dict() - - def load_state_dict(self, state_dict): - """Load an optimizer state dict. - - In general we should prefer the configuration of the existing optimizer - instance (e.g., learning rate) over that found in the state_dict. This - allows us to resume training from a checkpoint using a new set of - optimizer args. - """ - self.optimizer.load_state_dict(state_dict) - - # override learning rate, momentum, etc. with latest values - for group in self.optimizer.param_groups: - group.update(self.optimizer_config) - - def step(self, closure=None): - """Performs a single optimization step.""" - return self.optimizer.step(closure) - - def zero_grad(self): - """Clears the gradients of all optimized parameters.""" - for group in self.optimizer.param_groups: - for p in group['params']: - p.grad = None - - return self.optimizer.zero_grad() diff --git a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/__init__.py b/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/__init__.py deleted file mode 100644 index 0d637eaf..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/__init__.py +++ /dev/null @@ -1,39 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import importlib -import os - -from .fairseq_lr_scheduler import FairseqLRScheduler - - -LR_SCHEDULER_REGISTRY = {} - - -def build_lr_scheduler(args, optimizer): - return LR_SCHEDULER_REGISTRY[args.lr_scheduler](args, optimizer) - - -def register_lr_scheduler(name): - """Decorator to register a new LR scheduler.""" - - def register_lr_scheduler_cls(cls): - if name in LR_SCHEDULER_REGISTRY: - raise ValueError('Cannot register duplicate LR scheduler ({})'.format(name)) - if not issubclass(cls, FairseqLRScheduler): - raise ValueError('LR Scheduler ({}: {}) must extend FairseqLRScheduler'.format(name, cls.__name__)) - LR_SCHEDULER_REGISTRY[name] = cls - return cls - - return register_lr_scheduler_cls - - -# automatically import any Python files in the optim/lr_scheduler/ directory -for file in os.listdir(os.path.dirname(__file__)): - if file.endswith('.py') and not file.startswith('_'): - module = file[:file.find('.py')] - importlib.import_module('fairseq.optim.lr_scheduler.' + module) diff --git a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/fairseq_lr_scheduler.py b/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/fairseq_lr_scheduler.py deleted file mode 100644 index b7db369c..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/fairseq_lr_scheduler.py +++ /dev/null @@ -1,44 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -from .. import FairseqOptimizer - - -class FairseqLRScheduler(object): - - def __init__(self, args, optimizer): - super().__init__() - if not isinstance(optimizer, FairseqOptimizer): - raise ValueError('optimizer must be an instance of FairseqOptimizer') - self.args = args - self.optimizer = optimizer - self.best = None - - @staticmethod - def add_args(parser): - """Add arguments to the parser for this LR scheduler.""" - pass - - def state_dict(self): - """Return the LR scheduler state dict.""" - return {'best': self.best} - - def load_state_dict(self, state_dict): - """Load an LR scheduler state dict.""" - self.best = state_dict['best'] - - def step(self, epoch, val_loss=None): - """Update the learning rate at the end of the given epoch.""" - if val_loss is not None: - if self.best is None: - self.best = val_loss - else: - self.best = min(self.best, val_loss) - - def step_update(self, num_updates): - """Update the learning rate after each update.""" - return self.optimizer.get_lr() diff --git a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/fixed_schedule.py b/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/fixed_schedule.py deleted file mode 100644 index e8fe55ae..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/fixed_schedule.py +++ /dev/null @@ -1,57 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -from . import FairseqLRScheduler, register_lr_scheduler - - -@register_lr_scheduler('fixed') -class FixedSchedule(FairseqLRScheduler): - """Decay the LR on a fixed schedule.""" - - def __init__(self, args, optimizer): - super().__init__(args, optimizer) - - # set defaults - args.warmup_updates = getattr(args, 'warmup_updates', 0) or 0 - - self.lr = args.lr[0] - if args.warmup_updates > 0: - self.warmup_factor = 1. / args.warmup_updates - else: - self.warmup_factor = 1 - - @staticmethod - def add_args(parser): - """Add arguments to the parser for this LR scheduler.""" - parser.add_argument('--force-anneal', '--fa', type=int, metavar='N', - help='force annealing at specified epoch') - parser.add_argument('--warmup-updates', default=0, type=int, metavar='N', - help='warmup the learning rate linearly for the first N updates') - - def get_next_lr(self, epoch): - lrs = self.args.lr - if self.args.force_anneal is None or epoch < self.args.force_anneal: - # use fixed LR schedule - next_lr = lrs[min(epoch, len(lrs) - 1)] - else: - # annneal based on lr_shrink - next_lr = lrs[-1] * self.args.lr_shrink ** (epoch + 1 - self.args.force_anneal) - return next_lr - - def step(self, epoch, val_loss=None): - """Update the learning rate at the end of the given epoch.""" - super().step(epoch, val_loss) - self.lr = self.get_next_lr(epoch) - self.optimizer.set_lr(self.warmup_factor * self.lr) - return self.optimizer.get_lr() - - def step_update(self, num_updates): - """Update the learning rate after each update.""" - if self.args.warmup_updates > 0 and num_updates <= self.args.warmup_updates: - self.warmup_factor = num_updates / float(self.args.warmup_updates) - self.optimizer.set_lr(self.warmup_factor * self.lr) - return self.optimizer.get_lr() diff --git a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/inverse_square_root_schedule.py b/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/inverse_square_root_schedule.py deleted file mode 100644 index 1d034714..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/inverse_square_root_schedule.py +++ /dev/null @@ -1,75 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -from . import FairseqLRScheduler, register_lr_scheduler - -@register_lr_scheduler('inverse_sqrt') -class InverseSquareRootSchedule(FairseqLRScheduler): - """Decay the LR based on the inverse square root of the update number. - - We also support a warmup phase where we linearly increase the learning rate - from some initial learning rate (`--warmup-init-lr`) until the configured - learning rate (`--lr`). Thereafter we decay proportional to the number of - updates, with a decay factor set to align with the configured learning rate. - - During warmup: - - lrs = torch.linspace(args.warmup_init_lr, args.lr, args.warmup_updates) - lr = lrs[update_num] - - After warmup: - - lr = decay_factor / sqrt(update_num) - - where - - decay_factor = args.lr * sqrt(args.warmup_updates) - """ - - def __init__(self, args, optimizer): - super().__init__(args, optimizer) - if len(args.lr) > 1: - raise ValueError( - 'Cannot use a fixed learning rate schedule with inverse_sqrt.' - ' Consider --lr-scheduler=fixed instead.' - ) - warmup_end_lr = args.lr[0] - if args.warmup_init_lr < 0: - args.warmup_init_lr = warmup_end_lr - - # linearly warmup for the first args.warmup_updates - self.lr_step = (warmup_end_lr - args.warmup_init_lr) / args.warmup_updates - - # then, decay prop. to the inverse square root of the update number - self.decay_factor = warmup_end_lr * args.warmup_updates**0.5 - - # initial learning rate - self.lr = args.warmup_init_lr - self.optimizer.set_lr(self.lr) - - @staticmethod - def add_args(parser): - """Add arguments to the parser for this LR scheduler.""" - parser.add_argument('--warmup-updates', default=4000, type=int, metavar='N', - help='warmup the learning rate linearly for the first N updates') - parser.add_argument('--warmup-init-lr', default=-1, type=float, metavar='LR', - help='initial learning rate during warmup phase; default is args.lr') - - def step(self, epoch, val_loss=None): - """Update the learning rate at the end of the given epoch.""" - super().step(epoch, val_loss) - # we don't change the learning rate at epoch boundaries - return self.optimizer.get_lr() - - def step_update(self, num_updates): - """Update the learning rate after each update.""" - if num_updates < self.args.warmup_updates: - self.lr = self.args.warmup_init_lr + num_updates * self.lr_step - else: - self.lr = self.decay_factor * num_updates**-0.5 - self.optimizer.set_lr(self.lr) - return self.lr diff --git a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/reduce_lr_on_plateau.py b/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/reduce_lr_on_plateau.py deleted file mode 100644 index f822c855..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/lr_scheduler/reduce_lr_on_plateau.py +++ /dev/null @@ -1,46 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import torch.optim.lr_scheduler - -from . import FairseqLRScheduler, register_lr_scheduler - - -@register_lr_scheduler('reduce_lr_on_plateau') -class ReduceLROnPlateau(FairseqLRScheduler): - """Decay the LR by a factor every time the validation loss plateaus.""" - - def __init__(self, args, optimizer): - super().__init__(args, optimizer) - if len(args.lr) > 1: - raise ValueError( - 'Cannot use a fixed learning rate schedule with reduce_lr_on_plateau.' - ' Consider --lr-scheduler=fixed instead.' - ) - self.lr_scheduler = torch.optim.lr_scheduler.ReduceLROnPlateau( - self.optimizer.optimizer, patience=0, factor=args.lr_shrink) - - def state_dict(self): - """Return the LR scheduler state dict.""" - return { - 'best': self.lr_scheduler.best, - 'last_epoch': self.lr_scheduler.last_epoch, - } - - def load_state_dict(self, state_dict): - """Load an LR scheduler state dict.""" - self.lr_scheduler.best = state_dict['best'] - if 'last_epoch' in state_dict: - self.lr_scheduler.last_epoch = state_dict['last_epoch'] - - def step(self, epoch, val_loss=None): - """Update the learning rate at the end of the given epoch.""" - if val_loss is not None: - self.lr_scheduler.step(val_loss, epoch) - else: - self.lr_scheduler.last_epoch = epoch - return self.optimizer.get_lr() diff --git a/PyTorch/NLP/Transformer/fairseq/optim/nag.py b/PyTorch/NLP/Transformer/fairseq/optim/nag.py deleted file mode 100644 index 34c685cd..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/nag.py +++ /dev/null @@ -1,77 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -from torch.optim.optimizer import Optimizer, required - -from . import FairseqOptimizer, register_optimizer - - -@register_optimizer('nag') -class FairseqNAG(FairseqOptimizer): - def __init__(self, args, params): - super().__init__(args, params) - self._optimizer = NAG(params, **self.optimizer_config) - - @property - def optimizer_config(self): - """ - Return a kwarg dictionary that will be used to override optimizer - args stored in checkpoints. This allows us to load a checkpoint and - resume training using a different set of optimizer args, e.g., with a - different learning rate. - """ - return { - 'lr': self.args.lr[0], - 'momentum': self.args.momentum, - 'weight_decay': self.args.weight_decay, - } - - -class NAG(Optimizer): - def __init__(self, params, lr=required, momentum=0, weight_decay=0): - defaults = dict(lr=lr, lr_old=lr, momentum=momentum, weight_decay=weight_decay) - super(NAG, self).__init__(params, defaults) - - def step(self, closure=None): - """Performs a single optimization step. - - Arguments: - closure (callable, optional): A closure that reevaluates the model - and returns the loss. - """ - loss = None - if closure is not None: - loss = closure() - - for group in self.param_groups: - weight_decay = group['weight_decay'] - momentum = group['momentum'] - lr = group['lr'] - lr_old = group.get('lr_old', lr) - lr_correct = lr / lr_old - - for p in group['params']: - if p.grad is None: - continue - - d_p = p.grad.data - param_state = self.state[p] - if 'momentum_buffer' not in param_state: - param_state['momentum_buffer'] = d_p.clone().zero_() - - buf = param_state['momentum_buffer'] - - if weight_decay != 0: - p.data.mul_(1 - lr * weight_decay) - p.data.add_(momentum * momentum * lr_correct, buf) - p.data.add_(-(1 + momentum) * lr, d_p) - - buf.mul_(momentum * lr_correct).add_(-lr, d_p) - - group['lr_old'] = lr - - return loss diff --git a/PyTorch/NLP/Transformer/fairseq/optim/sgd.py b/PyTorch/NLP/Transformer/fairseq/optim/sgd.py deleted file mode 100644 index 4304e805..00000000 --- a/PyTorch/NLP/Transformer/fairseq/optim/sgd.py +++ /dev/null @@ -1,31 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. - -import torch.optim - -from . import FairseqOptimizer, register_optimizer - - -@register_optimizer('sgd') -class SGD(FairseqOptimizer): - def __init__(self, args, params): - super().__init__(args, params) - self._optimizer = torch.optim.SGD(params, **self.optimizer_config) - - @property - def optimizer_config(self): - """ - Return a kwarg dictionary that will be used to override optimizer - args stored in checkpoints. This allows us to load a checkpoint and - resume training using a different set of optimizer args, e.g., with a - different learning rate. - """ - return { - 'lr': self.args.lr[0], - 'momentum': self.args.momentum, - 'weight_decay': self.args.weight_decay, - } diff --git a/PyTorch/NLP/Transformer/fairseq/options.py b/PyTorch/NLP/Transformer/fairseq/options.py deleted file mode 100644 index acc5cfde..00000000 --- a/PyTorch/NLP/Transformer/fairseq/options.py +++ /dev/null @@ -1,342 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import argparse -import os - -import torch - -from fairseq.models import ARCH_MODEL_REGISTRY, ARCH_CONFIG_REGISTRY -from fairseq.criterions import CRITERION_REGISTRY -from fairseq.optim import OPTIMIZER_REGISTRY -from fairseq.optim.lr_scheduler import LR_SCHEDULER_REGISTRY - - -def get_training_parser(): - parser = get_parser('Trainer') - add_dataset_args(parser, train=True, gen=True) - add_distributed_training_args(parser) - add_model_args(parser) - add_optimization_args(parser) - add_checkpoint_args(parser) - add_inference_args(parser) - add_perf_args(parser) - return parser - - -def get_inference_parser(): - parser = get_parser('Generation') - add_dataset_args(parser, gen=True) - add_inference_args(parser) - add_perf_args(parser) - return parser - - -def parse_args_and_arch(parser, input_args=None, parse_known=False): - # The parser doesn't know about model/criterion/optimizer-specific args, so - # we parse twice. First we parse the model/criterion/optimizer, then we - # parse a second time after adding the *-specific arguments. - # If input_args is given, we will parse those args instead of sys.argv. - args, _ = parser.parse_known_args(input_args) - - # Add model-specific args to parser. - if hasattr(args, 'arch'): - model_specific_group = parser.add_argument_group( - 'Model-specific configuration', - # Only include attributes which are explicitly given as command-line - # arguments or which have default values. - argument_default=argparse.SUPPRESS, - ) - ARCH_MODEL_REGISTRY[args.arch].add_args(model_specific_group) - - # Add *-specific args to parser. - if hasattr(args, 'optimizer'): - OPTIMIZER_REGISTRY[args.optimizer].add_args(parser) - if hasattr(args, 'lr_scheduler'): - LR_SCHEDULER_REGISTRY[args.lr_scheduler].add_args(parser) - - # Parse a second time. - if parse_known: - args, extra = parser.parse_known_args(input_args) - else: - args = parser.parse_args(input_args) - extra = None - - # Post-process args. - if hasattr(args, 'max_sentences_valid') and args.max_sentences_valid is None: - args.max_sentences_valid = args.max_sentences - - args.max_positions = (args.max_source_positions, args.max_target_positions) - - if hasattr(args, 'target_bleu') and (args.online_eval or args.target_bleu) and not args.remove_bpe: - args.remove_bpe = '@@ ' - - # Apply architecture configuration. - if hasattr(args, 'arch'): - ARCH_CONFIG_REGISTRY[args.arch](args) - - if parse_known: - return args, extra - else: - return args - - -def get_parser(desc): - parser = argparse.ArgumentParser( - description='Facebook AI Research Sequence-to-Sequence Toolkit -- ' + desc) - parser.add_argument('--log-interval', type=int, default=500, metavar='N', - help='print aggregated stats and flush json log every N iteration') - parser.add_argument('--seed', default=1, type=int, metavar='N', - help='pseudo random number generator seed') - parser.add_argument('--amp', action='store_true', - help='use Automatic Mixed Precision') - parser.add_argument('--stat-file', type=str, default='run_log.json', - help='Name of the file containing DLLogger output') - parser.add_argument('--save-dir', metavar='DIR', default='results', - help='path to save checkpoints and logs') - parser.add_argument('--do-sanity-check', action='store_true', - help='Perform evaluation on test set before running the training') - - return parser - - -def add_dataset_args(parser, train=False, gen=False): - group = parser.add_argument_group('Dataset and data loading') - group.add_argument('--max-tokens', type=int, metavar='N', - help='maximum number of tokens in a batch') - group.add_argument('--max-sentences', '--batch-size', type=int, metavar='N', - help='maximum number of sentences in a batch') - parser.add_argument('-s', '--source-lang', default=None, metavar='SRC', - help='source language') - parser.add_argument('-t', '--target-lang', default=None, metavar='TARGET', - help='target language') - parser.add_argument('--raw-text', action='store_true', - help='load raw text dataset') - parser.add_argument('--left-pad-source', default=True, type=bool, metavar='BOOL', - help='pad the source on the left (default: True)') - parser.add_argument('--left-pad-target', default=False, type=bool, metavar='BOOL', - help='pad the target on the left (default: False)') - parser.add_argument('--max-source-positions', default=1024, type=int, metavar='N', - help='max number of tokens in the source sequence') - parser.add_argument('--max-target-positions', default=1024, type=int, metavar='N', - help='max number of tokens in the target sequence') - parser.add_argument('--pad-sequence', default=1, type=int, metavar='N', - help='Pad sequences to a multiple of N') - if train: - parser.add_argument('data', metavar='DIR', help='path to data directory') - group.add_argument('--train-subset', default='train', metavar='SPLIT', - choices=['train', 'valid', 'test'], - help='data subset to use for training (train, valid, test)') - group.add_argument('--valid-subset', default='valid', metavar='SPLIT', - help='comma separated list of data subsets to use for validation' - ' (train, valid, valid1, test, test1)') - group.add_argument('--max-sentences-valid', type=int, metavar='N', - help='maximum number of sentences in a validation batch' - ' (defaults to --max-sentences)') - if gen: - group.add_argument('--gen-subset', default='test', metavar='SPLIT', - help='data subset to generate (train, valid, test)') - group.add_argument('--num-shards', default=1, type=int, metavar='N', - help='shard generation over N shards') - group.add_argument('--shard-id', default=0, type=int, metavar='ID', - help='id of the shard to generate (id < num_shards)') - return group - - -def add_distributed_training_args(parser): - group = parser.add_argument_group('Distributed training') - group.add_argument('--distributed-world-size', type=int, metavar='N', - default=torch.cuda.device_count(), - help='total number of GPUs across all nodes (default: all visible GPUs)') - group.add_argument('--distributed-rank', default=os.getenv('LOCAL_RANK', 0), type=int, - help='rank of the current worker') - group.add_argument('--local_rank', default=0, type=int, - help='rank of the current worker') - group.add_argument('--distributed-backend', default='nccl', type=str, - help='distributed backend') - group.add_argument('--distributed-init-method', default=None, type=str, - help='typically tcp://hostname:port that will be used to ' - 'establish initial connetion') - group.add_argument('--distributed-port', default=-1, type=int, - help='port number (not required if using --distributed-init-method)') - group.add_argument('--device-id', default=0, type=int, - help='which GPU to use (usually configured automatically)') - return group - - -def add_optimization_args(parser): - group = parser.add_argument_group('Optimization') - group.add_argument('--max-epoch', '--me', default=0, type=int, metavar='N', - help='force stop training at specified epoch') - group.add_argument('--max-update', '--mu', default=0, type=int, metavar='N', - help='force stop training at specified update') - group.add_argument('--target-bleu', default=0.0, type=float, metavar='TARGET', - help='force stop training after reaching target bleu') - group.add_argument('--clip-norm', default=25, type=float, metavar='NORM', - help='clip threshold of gradients') - group.add_argument('--update-freq', default=[1], nargs='+', type=int, - help='update parameters every N_i batches, when in epoch i') - - # Optimizer definitions can be found under fairseq/optim/ - group.add_argument('--optimizer', default='nag', metavar='OPT', - choices=OPTIMIZER_REGISTRY.keys(), - help='optimizer: {} (default: nag)'.format(', '.join(OPTIMIZER_REGISTRY.keys()))) - group.add_argument('--lr', '--learning-rate', default=[0.25], nargs='+', type=float, - help='learning rate for the first N epochs; all epochs >N using LR_N' - ' (note: this may be interpreted differently depending on --lr-scheduler)') - group.add_argument('--momentum', default=0.99, type=float, metavar='M', - help='momentum factor') - group.add_argument('--weight-decay', '--wd', default=0.0, type=float, metavar='WD', - help='weight decay') - - # Learning rate schedulers can be found under fairseq/optim/lr_scheduler/ - group.add_argument('--lr-scheduler', default='reduce_lr_on_plateau', - help='learning rate scheduler: {} (default: reduce_lr_on_plateau)'.format( - ', '.join(LR_SCHEDULER_REGISTRY.keys()))) - group.add_argument('--lr-shrink', default=0.1, type=float, metavar='LS', - help='learning rate shrink factor for annealing, lr_new = (lr * lr_shrink)') - group.add_argument('--min-lr', default=1e-5, type=float, metavar='LR', - help='minimum learning rate') - - # Criterion args - parser.add_argument('--label-smoothing', default=0., type=float, metavar='D', - help='epsilon for label smoothing, 0 means no label smoothing') - - return group - - -def add_checkpoint_args(parser): - group = parser.add_argument_group('Checkpointing') - group.add_argument('--restore-file', default='checkpoint_last.pt', - help='filename in save-dir from which to load checkpoint') - group.add_argument('--save-interval', type=int, default=1, metavar='N', - help='save a checkpoint every N epochs') - group.add_argument('--no-save', action='store_true', - help='don\'t save models or checkpoints') - group.add_argument('--no-epoch-checkpoints', action='store_true', - help='only store last and best checkpoints') - group.add_argument('--validate-interval', type=int, default=1, metavar='N', - help='validate every N epochs') - return group - - -def add_common_eval_args(group): - group.add_argument('--path', metavar='FILE', - help='path(s) to model file(s), colon separated') - group.add_argument('--file', metavar='FILE', default=None, type=str, - help='path to a file with input data for inference') - group.add_argument('--remove-bpe', nargs='?', const='@@ ', default=None, - help='remove BPE tokens before scoring') - group.add_argument('--cpu', action='store_true', help='generate on CPU') - group.add_argument('--quiet', action='store_true', - help='only print final scores') - - -def add_inference_args(parser): - group = parser.add_argument_group('Generation') - add_common_eval_args(group) - group.add_argument('--beam', default=4, type=int, metavar='N', - help='beam size') - group.add_argument('--nbest', default=1, type=int, metavar='N', - help='number of hypotheses to output') - group.add_argument('--max-len-a', default=0, type=float, metavar='N', - help=('generate sequences of maximum length ax + b, ' - 'where x is the source length')) - group.add_argument('--max-len-b', default=200, type=int, metavar='N', - help=('generate sequences of maximum length ax + b, ' - 'where x is the source length')) - group.add_argument('--min-len', default=1, type=float, metavar='N', - help=('minimum generation length')) - group.add_argument('--no-early-stop', action='store_true', - help=('continue searching even after finalizing k=beam ' - 'hypotheses; this is more correct, but increases ' - 'generation time by 50%%')) - group.add_argument('--unnormalized', action='store_true', - help='compare unnormalized hypothesis scores') - group.add_argument('--no-beamable-mm', action='store_true', - help='don\'t use BeamableMM in attention layers') - group.add_argument('--lenpen', default=1, type=float, - help='length penalty: <1.0 favors shorter, >1.0 favors longer sentences') - group.add_argument('--unkpen', default=0, type=float, - help='unknown word penalty: <0 produces more unks, >0 produces fewer') - group.add_argument('--replace-unk', nargs='?', const=True, default=None, - help='perform unknown replacement (optionally with alignment dictionary)') - group.add_argument('--prefix-size', default=0, type=int, metavar='PS', - help='initialize generation by target prefix of given length') - group.add_argument('--sampling', action='store_true', - help='sample hypotheses instead of using beam search') - group.add_argument('--sampling-topk', default=-1, type=int, metavar='PS', - help='sample from top K likely next words instead of all words') - group.add_argument('--sampling-temperature', default=1, type=float, metavar='N', - help='temperature for random sampling') - group.add_argument('--print-alignment', action='store_true', - help='if set, uses attention feedback to compute and print alignment to source tokens') - group.add_argument('--online-eval', action='store_true', - help='score model at the end of epoch') - group.add_argument('--save-predictions', action='store_true', - help='Save predictions produced with online evaluation') - group.add_argument('--test-cased-bleu', action='store_true', - help='Use cased bleu for online eval') - group.add_argument('--bpe-codes', default=None, type=str, metavar='CODES', - help='file with bpe codes') - group.add_argument('--buffer-size', default=64, type=int, metavar='N', - help='read this many sentences into a buffer before processing them') - group.add_argument('--fp16', action='store_true', help='use fp16 precision') - return group - -def add_model_args(parser): - group = parser.add_argument_group('Model configuration') - - # Model definitions can be found under fairseq/models/ - # - # The model architecture can be specified in several ways. - # In increasing order of priority: - # 1) model defaults (lowest priority) - # 2) --arch argument - group.add_argument( - '--arch', '-a', default='fconv', metavar='ARCH', required=True, - choices=ARCH_MODEL_REGISTRY.keys(), - help='model architecture: {} (default: fconv)'.format( - ', '.join(ARCH_MODEL_REGISTRY.keys())), - ) - - # Criterion definitions can be found under fairseq/criterions/ - group.add_argument( - '--criterion', default='cross_entropy', metavar='CRIT', - choices=CRITERION_REGISTRY.keys(), - help='training criterion: {} (default: cross_entropy)'.format( - ', '.join(CRITERION_REGISTRY.keys())), - ) - - return group - - -def add_perf_args(parser): - group = parser.add_argument_group('Performance') - group.add_argument('--fuse-dropout-add', action='store_true', - help='Fuse dropout and residual adds.') - group.add_argument('--fuse-relu-dropout', action='store_true', - help='Fuse Relu and Dropout.') - group.add_argument('--fuse-layer-norm', action='store_true', - help='Use APEX\'s FusedLayerNorm instead of torch.nn.LayerNorm') - - return group diff --git a/PyTorch/NLP/Transformer/fairseq/prefixes/nonbreaking_prefix.en b/PyTorch/NLP/Transformer/fairseq/prefixes/nonbreaking_prefix.en deleted file mode 100644 index c19ffd89..00000000 --- a/PyTorch/NLP/Transformer/fairseq/prefixes/nonbreaking_prefix.en +++ /dev/null @@ -1,135 +0,0 @@ -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -#Anything in this file, followed by a period (and an upper-case word), does NOT indicate an end-of-sentence marker. -#Special cases are included for prefixes that ONLY appear before 0-9 numbers. - -#any single upper case letter followed by a period is not a sentence ender (excluding I occasionally, but we leave it in) -#usually upper case letters are initials in a name -A -B -C -D -E -F -G -H -I -J -K -L -M -N -O -P -Q -R -S -T -U -V -W -X -Y -Z - -#List of titles. These are often followed by upper-case names, but do not indicate sentence breaks -Adj -Adm -Adv -Asst -Bart -Bldg -Brig -Bros -Capt -Cmdr -Col -Comdr -Con -Corp -Cpl -DR -Dr -Drs -Ens -Gen -Gov -Hon -Hr -Hosp -Insp -Lt -MM -MR -MRS -MS -Maj -Messrs -Mlle -Mme -Mr -Mrs -Ms -Msgr -Op -Ord -Pfc -Ph -Prof -Pvt -Rep -Reps -Res -Rev -Rt -Sen -Sens -Sfc -Sgt -Sr -St -Supt -Surg - -#misc - odd period-ending items that NEVER indicate breaks (p.m. does NOT fall into this category - it sometimes ends a sentence) -v -vs -i.e -rev -e.g - -#Numbers only. These should only induce breaks when followed by a numeric sequence -# add NUMERIC_ONLY after the word for this function -#This case is mostly for the english "No." which can either be a sentence of its own, or -#if followed by a number, a non-breaking prefix -No #NUMERIC_ONLY# -Nos -Art #NUMERIC_ONLY# -Nr -pp #NUMERIC_ONLY# - -#month abbreviations -Jan -Feb -Mar -Apr -#May is a full word -Jun -Jul -Aug -Sep -Oct -Nov -Dec diff --git a/PyTorch/NLP/Transformer/fairseq/sequence_generator.py b/PyTorch/NLP/Transformer/fairseq/sequence_generator.py deleted file mode 100644 index 67d008db..00000000 --- a/PyTorch/NLP/Transformer/fairseq/sequence_generator.py +++ /dev/null @@ -1,567 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import math - -import torch -import torch.nn.functional as F -from torch.cuda import amp - -from fairseq import utils -from fairseq.models import FairseqIncrementalDecoder - - -class SequenceGenerator(object): - def __init__( - self, models, vocab_meta, maxlen, beam_size=1, minlen=1, stop_early=True, - normalize_scores=True, len_penalty=1, unk_penalty=0, retain_dropout=False, - sampling=False, sampling_topk=-1, sampling_temperature=1, use_amp=False - ): - """Generates translations of a given source sentence. - Args: - min/maxlen: The length of the generated output will be bounded by - minlen and maxlen (not including the end-of-sentence marker). - stop_early: Stop generation immediately after we finalize beam_size - hypotheses, even though longer hypotheses might have better - normalized scores. - normalize_scores: Normalize scores by the length of the output. - """ - self.models = models - self.pad = vocab_meta['pad'] - self.unk = vocab_meta['unk'] - self.eos = vocab_meta['eos'] - self.vocab_size = vocab_meta['len'] - self.beam_size = beam_size - self.minlen = minlen - #max_decoder_len = min(m.max_decoder_positions() for m in self.models) - #max_decoder_len -= 1 # we define maxlen not including the EOS marker - #self.maxlen = max_decoder_len if maxlen is None else min(maxlen, max_decoder_len) - self.maxlen = maxlen - self.stop_early = stop_early - self.normalize_scores = normalize_scores - self.len_penalty = len_penalty - self.unk_penalty = unk_penalty - self.retain_dropout = retain_dropout - self.sampling = sampling - self.sampling_topk = sampling_topk - self.sampling_temperature = sampling_temperature - self.use_amp = use_amp - - def cuda(self): - for model in self.models: - model.cuda() - return self - - def generate_batched_itr( - self, data_itr, beam_size=None, maxlen_a=0.0, maxlen_b=None, - cuda=False, timer=None, prefix_size=0, - ): - """Iterate over a batched dataset and yield individual translations. - Args: - maxlen_a/b: generate sequences of maximum length ax + b, - where x is the source sentence length. - cuda: use GPU for generation - timer: StopwatchMeter for timing generations. - """ - if maxlen_b is None: - maxlen_b = self.maxlen - - for sample in data_itr: - s = utils.move_to_cuda(sample) if cuda else sample - if 'net_input' not in s: - continue - input = s['net_input'] - srclen = input['src_tokens'].size(1) - if timer is not None: - timer.start() - with torch.no_grad(): - hypos = self.generate( - input['src_tokens'], - input['src_lengths'], - beam_size=beam_size, - maxlen=int(maxlen_a * srclen + maxlen_b), - prefix_tokens=s['target'][:, :prefix_size] if prefix_size > 0 else None, - ) - if timer is not None: - timer.stop(sum(len(h[0]['tokens']) for h in hypos)) - for i, id in enumerate(s['id'].data): - # remove padding - src = utils.strip_pad(input['src_tokens'].data[i, :], self.pad) - ref = utils.strip_pad(s['target'].data[i, :], self.pad) if s['target'] is not None else None - yield id, src, ref, hypos[i] - - def generate(self, src_tokens, src_lengths, beam_size=None, maxlen=None, prefix_tokens=None): - """Generate a batch of translations.""" - with torch.no_grad(): - with amp.autocast(enabled=self.use_amp): - return self._generate(src_tokens, src_lengths, beam_size, maxlen, prefix_tokens) - - def _generate(self, src_tokens, src_lengths, beam_size=None, maxlen=None, prefix_tokens=None): - bsz, srclen = src_tokens.size() - maxlen = min(maxlen, self.maxlen) if maxlen is not None else self.maxlen - - # the max beam size is the dictionary size - 1, since we never select pad - beam_size = beam_size if beam_size is not None else self.beam_size - beam_size = min(beam_size, self.vocab_size - 1) - - encoder_outs = [] - incremental_states = {} - for model in self.models: - if not self.retain_dropout: - model.eval() - if isinstance(model.decoder, FairseqIncrementalDecoder): - incremental_states[model] = {} - else: - incremental_states[model] = None - - # compute the encoder output for each beam - encoder_out = model.encoder( - src_tokens.repeat(1, beam_size).view(-1, srclen), - src_lengths.expand(beam_size, src_lengths.numel()).t().contiguous().view(-1), - ) - encoder_outs.append(encoder_out) - - # initialize buffers - scores = src_tokens.data.new(bsz * beam_size, maxlen + 1).float().fill_(0) - scores_buf = scores.clone() - tokens = src_tokens.data.new(bsz * beam_size, maxlen + 2).fill_(self.pad) - tokens_buf = tokens.clone() - tokens[:, 0] = self.eos - attn, attn_buf = None, None - nonpad_idxs = None - - # list of completed sentences - finalized = [[] for i in range(bsz)] - finished = [False for i in range(bsz)] - worst_finalized = [{'idx': None, 'score': -math.inf} for i in range(bsz)] - num_remaining_sent = bsz - - # number of candidate hypos per step - cand_size = 2 * beam_size # 2 x beam size in case half are EOS - - # offset arrays for converting between different indexing schemes - bbsz_offsets = (torch.arange(0, bsz) * beam_size).unsqueeze(1).type_as(tokens) - cand_offsets = torch.arange(0, cand_size).type_as(tokens) - - # helper function for allocating buffers on the fly - buffers = {} - - def buffer(name, type_of=tokens): # noqa - if name not in buffers: - buffers[name] = type_of.new() - return buffers[name] - - def is_finished(sent, step, unfinalized_scores=None): - """ - Check whether we've finished generation for a given sentence, by - comparing the worst score among finalized hypotheses to the best - possible score among unfinalized hypotheses. - """ - assert len(finalized[sent]) <= beam_size - if len(finalized[sent]) == beam_size: - if self.stop_early or step == maxlen or unfinalized_scores is None: - return True - # stop if the best unfinalized score is worse than the worst - # finalized one - best_unfinalized_score = unfinalized_scores[sent].max() - if self.normalize_scores: - best_unfinalized_score /= maxlen ** self.len_penalty - if worst_finalized[sent]['score'] >= best_unfinalized_score: - return True - return False - - def finalize_hypos(step, bbsz_idx, eos_scores, unfinalized_scores=None): - """ - Finalize the given hypotheses at this step, while keeping the total - number of finalized hypotheses per sentence <= beam_size. - Note: the input must be in the desired finalization order, so that - hypotheses that appear earlier in the input are preferred to those - that appear later. - Args: - step: current time step - bbsz_idx: A vector of indices in the range [0, bsz*beam_size), - indicating which hypotheses to finalize - eos_scores: A vector of the same size as bbsz_idx containing - scores for each hypothesis - unfinalized_scores: A vector containing scores for all - unfinalized hypotheses - """ - assert bbsz_idx.numel() == eos_scores.numel() - - # clone relevant token and attention tensors - tokens_clone = tokens.index_select(0, bbsz_idx) - tokens_clone = tokens_clone[:, 1:step + 2] # skip the first index, which is EOS - tokens_clone[:, step] = self.eos - attn_clone = attn.index_select(0, bbsz_idx)[:, :, 1:step + 2] if attn is not None else None - - # compute scores per token position - pos_scores = scores.index_select(0, bbsz_idx)[:, :step + 1] - pos_scores[:, step] = eos_scores - # convert from cumulative to per-position scores - pos_scores[:, 1:] = pos_scores[:, 1:] - pos_scores[:, :-1] - - # normalize sentence-level scores - if self.normalize_scores: - eos_scores /= (step + 1) ** self.len_penalty - - cum_unfin = [] - prev = 0 - for f in finished: - if f: - prev += 1 - else: - cum_unfin.append(prev) - - sents_seen = set() - for i, (idx, score) in enumerate(zip(bbsz_idx.tolist(), eos_scores.tolist())): - unfin_idx = idx // beam_size - sent = unfin_idx + cum_unfin[unfin_idx] - - sents_seen.add((sent, unfin_idx)) - - def get_hypo(): - - if attn_clone is not None: - # remove padding tokens from attn scores - hypo_attn = attn_clone[i][nonpad_idxs[sent]] - _, alignment = hypo_attn.max(dim=0) - else: - hypo_attn = None - alignment = None - - return { - 'tokens': tokens_clone[i], - 'score': score, - 'attention': hypo_attn, # src_len x tgt_len - 'alignment': alignment, - 'positional_scores': pos_scores[i], - } - - if len(finalized[sent]) < beam_size: - finalized[sent].append(get_hypo()) - elif not self.stop_early and score > worst_finalized[sent]['score']: - # replace worst hypo for this sentence with new/better one - worst_idx = worst_finalized[sent]['idx'] - if worst_idx is not None: - finalized[sent][worst_idx] = get_hypo() - - # find new worst finalized hypo for this sentence - idx, s = min(enumerate(finalized[sent]), key=lambda r: r[1]['score']) - worst_finalized[sent] = { - 'score': s['score'], - 'idx': idx, - } - - newly_finished = [] - for sent, unfin_idx in sents_seen: - # check termination conditions for this sentence - if not finished[sent] and is_finished(sent, step, unfinalized_scores): - finished[sent] = True - newly_finished.append(unfin_idx) - return newly_finished - - reorder_state = None - batch_idxs = None - for step in range(maxlen + 1): # one extra step for EOS marker - # reorder decoder internal states based on the prev choice of beams - if reorder_state is not None: - if batch_idxs is not None: - # update beam indices to take into account removed sentences - corr = batch_idxs - torch.arange(batch_idxs.numel()).type_as(batch_idxs) - reorder_state.view(-1, beam_size).add_(corr.unsqueeze(-1) * beam_size) - for i, model in enumerate(self.models): - if isinstance(model.decoder, FairseqIncrementalDecoder): - model.decoder.reorder_incremental_state(incremental_states[model], reorder_state) - encoder_outs[i] = model.encoder.reorder_encoder_out(*encoder_outs[i], reorder_state) - - probs, avg_attn_scores = self._decode(tokens[:, :step + 1], encoder_outs, incremental_states) - if step == 0: - # at the first step all hypotheses are equally likely, so use - # only the first beam - probs = probs.unfold(0, 1, beam_size).squeeze(2).contiguous() - scores = scores.type_as(probs) - scores_buf = scores_buf.type_as(probs) - elif not self.sampling: - # make probs contain cumulative scores for each hypothesis - probs.add_(scores[:, step - 1].view(-1, 1)) - - probs[:, self.pad] = -math.inf # never select pad - probs[:, self.unk] -= self.unk_penalty # apply unk penalty - - # Record attention scores - if avg_attn_scores is not None: - if attn is None: - attn = scores.new(bsz * beam_size, src_tokens.size(1), maxlen + 2) - attn_buf = attn.clone() - nonpad_idxs = src_tokens.ne(self.pad) - attn[:, :, step + 1].copy_(avg_attn_scores) - - cand_scores = buffer('cand_scores', type_of=scores) - cand_indices = buffer('cand_indices') - cand_beams = buffer('cand_beams') - eos_bbsz_idx = buffer('eos_bbsz_idx') - eos_scores = buffer('eos_scores', type_of=scores) - if step < maxlen: - if prefix_tokens is not None and step < prefix_tokens.size(1): - probs_slice = probs.view(bsz, -1, probs.size(-1))[:, 0, :] - cand_scores = torch.gather( - probs_slice, dim=1, - index=prefix_tokens[:, step].view(-1, 1).data - ).expand(-1, cand_size) - cand_indices = prefix_tokens[:, step].view(-1, 1).expand(bsz, cand_size).data - cand_beams.resize_as_(cand_indices).fill_(0) - elif self.sampling: - assert self.pad == 1, 'sampling assumes the first two symbols can be ignored' - - if self.sampling_topk > 0: - values, indices = probs[:, 2:].topk(self.sampling_topk) - exp_probs = values.div_(self.sampling_temperature).exp() - if step == 0: - torch.multinomial(exp_probs, beam_size, replacement=True, out=cand_indices) - else: - torch.multinomial(exp_probs, 1, replacement=True, out=cand_indices) - torch.gather(exp_probs, dim=1, index=cand_indices, out=cand_scores) - torch.gather(indices, dim=1, index=cand_indices, out=cand_indices) - cand_indices.add_(2) - else: - exp_probs = probs.div_(self.sampling_temperature).exp_().view(-1, self.vocab_size) - - if step == 0: - # we exclude the first two vocab items, one of which is pad - torch.multinomial(exp_probs[:, 2:], beam_size, replacement=True, out=cand_indices) - else: - torch.multinomial(exp_probs[:, 2:], 1, replacement=True, out=cand_indices) - - cand_indices.add_(2) - torch.gather(exp_probs, dim=1, index=cand_indices, out=cand_scores) - - cand_scores.log_() - cand_indices = cand_indices.view(bsz, -1).repeat(1, 2) - cand_scores = cand_scores.view(bsz, -1).repeat(1, 2) - if step == 0: - cand_beams = torch.zeros(bsz, cand_size).type_as(cand_indices) - else: - cand_beams = torch.arange(0, beam_size).repeat(bsz, 2).type_as(cand_indices) - # make scores cumulative - cand_scores.add_( - torch.gather( - scores[:, step - 1].view(bsz, beam_size), dim=1, - index=cand_beams, - ) - ) - else: - # take the best 2 x beam_size predictions. We'll choose the first - # beam_size of these which don't predict eos to continue with. - torch.topk( - probs.view(bsz, -1), - k=min(cand_size, probs.view(bsz, -1).size(1) - 1), # -1 so we never select pad - out=(cand_scores, cand_indices), - ) - torch.div(cand_indices, self.vocab_size, out=cand_beams, rounding_mode='trunc') - cand_indices.fmod_(self.vocab_size) - else: - # finalize all active hypotheses once we hit maxlen - # pick the hypothesis with the highest prob of EOS right now - torch.sort( - probs[:, self.eos], - descending=True, - out=(eos_scores, eos_bbsz_idx), - ) - num_remaining_sent -= len(finalize_hypos( - step, eos_bbsz_idx, eos_scores)) - assert num_remaining_sent == 0 - break - - # cand_bbsz_idx contains beam indices for the top candidate - # hypotheses, with a range of values: [0, bsz*beam_size), - # and dimensions: [bsz, cand_size] - cand_bbsz_idx = cand_beams.add(bbsz_offsets) - - # finalize hypotheses that end in eos - eos_mask = cand_indices.eq(self.eos) - - finalized_sents = set() - if step >= self.minlen: - # only consider eos when it's among the top beam_size indices - torch.masked_select( - cand_bbsz_idx[:, :beam_size], - mask=eos_mask[:, :beam_size], - out=eos_bbsz_idx, - ) - if eos_bbsz_idx.numel() > 0: - torch.masked_select( - cand_scores[:, :beam_size], - mask=eos_mask[:, :beam_size], - out=eos_scores, - ) - finalized_sents = finalize_hypos( - step, eos_bbsz_idx, eos_scores, cand_scores) - num_remaining_sent -= len(finalized_sents) - - assert num_remaining_sent >= 0 - if num_remaining_sent == 0: - break - assert step < maxlen - - if len(finalized_sents) > 0: - new_bsz = bsz - len(finalized_sents) - - # construct batch_idxs which holds indices of batches to keep for the next pass - batch_mask = torch.ones(bsz).type_as(cand_indices) - batch_mask[cand_indices.new(finalized_sents)] = 0 - batch_idxs = batch_mask.nonzero().squeeze(-1) - - eos_mask = eos_mask[batch_idxs] - cand_beams = cand_beams[batch_idxs] - bbsz_offsets.resize_(new_bsz, 1) - cand_bbsz_idx = cand_beams.add(bbsz_offsets) - - cand_scores = cand_scores[batch_idxs] - cand_indices = cand_indices[batch_idxs] - if prefix_tokens is not None: - prefix_tokens = prefix_tokens[batch_idxs] - - scores = scores.view(bsz, -1)[batch_idxs].view(new_bsz * beam_size, -1) - scores_buf.resize_as_(scores) - tokens = tokens.view(bsz, -1)[batch_idxs].view(new_bsz * beam_size, -1) - tokens_buf.resize_as_(tokens) - if attn is not None: - attn = attn.view(bsz, -1)[batch_idxs].view(new_bsz * beam_size, attn.size(1), -1) - attn_buf.resize_as_(attn) - bsz = new_bsz - else: - batch_idxs = None - - # set active_mask so that values > cand_size indicate eos hypos - # and values < cand_size indicate candidate active hypos. - # After, the min values per row are the top candidate active hypos - active_mask = buffer('active_mask') - torch.add( - eos_mask.type_as(cand_offsets) * cand_size, - cand_offsets[:eos_mask.size(1)], - out=active_mask, - ) - - # get the top beam_size active hypotheses, which are just the hypos - # with the smallest values in active_mask - active_hypos, _ignore = buffer('active_hypos'), buffer('_ignore') - torch.topk( - active_mask, k=beam_size, dim=1, largest=False, - out=(_ignore, active_hypos) - ) - active_bbsz_idx = buffer('active_bbsz_idx') - torch.gather( - cand_bbsz_idx, dim=1, index=active_hypos, - out=active_bbsz_idx, - ) - active_scores = torch.gather( - cand_scores, dim=1, index=active_hypos, - out=scores[:, step].view(bsz, beam_size), - ) - - active_bbsz_idx = active_bbsz_idx.view(-1) - active_scores = active_scores.view(-1) - - # copy tokens and scores for active hypotheses - torch.index_select( - tokens[:, :step + 1], dim=0, index=active_bbsz_idx, - out=tokens_buf[:, :step + 1], - ) - torch.gather( - cand_indices, dim=1, index=active_hypos, - out=tokens_buf.view(bsz, beam_size, -1)[:, :, step + 1], - ) - if step > 0: - torch.index_select( - scores[:, :step], dim=0, index=active_bbsz_idx, - out=scores_buf[:, :step], - ) - torch.gather( - cand_scores, dim=1, index=active_hypos, - out=scores_buf.view(bsz, beam_size, -1)[:, :, step], - ) - - # copy attention for active hypotheses - if attn is not None: - torch.index_select( - attn[:, :, :step + 2], dim=0, index=active_bbsz_idx, - out=attn_buf[:, :, :step + 2], - ) - - # swap buffers - tokens, tokens_buf = tokens_buf, tokens - scores, scores_buf = scores_buf, scores - if attn is not None: - attn, attn_buf = attn_buf, attn - - # reorder incremental state in decoder - reorder_state = active_bbsz_idx - - # sort by score descending - for sent in range(len(finalized)): - finalized[sent] = sorted(finalized[sent], key=lambda r: r['score'], reverse=True) - - return finalized - - def _decode(self, tokens, encoder_outs, incremental_states): - if len(self.models) == 1: - return self._decode_one(tokens, self.models[0], encoder_outs[0], incremental_states, log_probs=True) - - avg_probs = None - avg_attn = None - for model, encoder_out in zip(self.models, encoder_outs): - probs, attn = self._decode_one(tokens, model, encoder_out, incremental_states, log_probs=False) - if avg_probs is None: - avg_probs = probs - else: - avg_probs.add_(probs) - if attn is not None: - if avg_attn is None: - avg_attn = attn - else: - avg_attn.add_(attn) - avg_probs.div_(len(self.models)) - avg_probs.log_() - if avg_attn is not None: - avg_attn.div_(len(self.models)) - return avg_probs, avg_attn - - def _decode_one(self, tokens, model, encoder_out, incremental_states, log_probs): - with torch.no_grad(): - if incremental_states[model] is not None: - decoder_out = list(model.decoder(tokens, encoder_out[0], encoder_out[1], incremental_state=incremental_states[model])) - else: - decoder_out = list(model.decoder(tokens, encoder_out[0], encoder_out[1])) - decoder_out[0] = decoder_out[0][:, -1, :] - attn = decoder_out[1] - if isinstance(attn, torch.Tensor) and attn.numel() == 0: - attn = None - if attn is not None: - attn = attn[:, -1, :] - - logits = decoder_out[0] - if log_probs: - probs = F.log_softmax(logits, dim=-1, dtype=torch.float32) - else: - probs = F.softmax(logits, dim=-1, dtype=torch.float32) - - return probs, attn diff --git a/PyTorch/NLP/Transformer/fairseq/tokenizer.py b/PyTorch/NLP/Transformer/fairseq/tokenizer.py deleted file mode 100644 index 1ae7772f..00000000 --- a/PyTorch/NLP/Transformer/fairseq/tokenizer.py +++ /dev/null @@ -1,300 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import os -from collections import Counter -import re - -import torch - - -SPACE_NORMALIZER = re.compile("\s+") - -path = os.path.join(os.path.dirname(os.path.abspath(__file__)),'prefixes/nonbreaking_prefix.en') -prefixes ={} - -with open(path, 'r') as f: - for line in f: - line = line.strip() - if line and not line[0] == '#': - match = re.search(r'(.*)[\s]+(\#NUMERIC_ONLY\#)', line) - if match: - prefixes[match.group(1)] = 2 - else: - prefixes[line] = 1 - -def get_unicode_categories(): - import sys - from collections import defaultdict - import unicodedata - cats = defaultdict(list) - for c in map(chr, range(sys.maxunicode + 1)): - cats[unicodedata.category(c)].append(c) - return cats - -NUMERICS = ''.join(get_unicode_categories()['No']) - -def tokenize_line(line): - line = SPACE_NORMALIZER.sub(" ", line) - line = line.strip() - return line - -def tokenize_en(line): - line = line.strip() - line = ' ' + line + ' ' - # remove ASCII junk - line = re.sub(r'\s+', ' ', line) - line = re.sub(r'[\x00-\x1F]', '', line) - #fix whitespaces - line = re.sub('\ +', ' ', line) - line = re.sub('^ ', '', line) - line = re.sub(' $', '', line) - #separate other special characters - line = re.sub(r'([^\s\.\'\`\,\-\w]|[_'+NUMERICS+'])', r' \g<1> ', line) - line = re.sub(r'(\w)\-(?=\w)', r'\g<1> @-@ ', line) - - #multidots stay together - line = re.sub(r'\.([\.]+)', r' DOTMULTI\g<1>', line) - while re.search(r'DOTMULTI\.', line): - line = re.sub(r'DOTMULTI\.([^\.])', r'DOTDOTMULTI \g<1>', line) - line = re.sub(r'DOTMULTI\.', r'DOTDOTMULTI', line) - - # separate out "," except if within numbers (5,300) - line = re.sub(r'([\D])[,]', r'\g<1> , ', line) - line = re.sub(r'[,]([\D])', r' , \g<1>', line) - - # separate "," after a number if it's the end of sentence - line = re.sub(r'(\d)[,]$', r'\g<1> ,', line) - - # split contractions right - line = re.sub(r'([\W\d])[\']([\W\d])', '\g<1> \' \g<2>', line) - line = re.sub(r'(\W)[\']([\w\D])', '\g<1> \' \g<2>', line) - line = re.sub(r'([\w\D])[\']([\W\d])', '\g<1> \' \g<2>', line) - line = re.sub(r'([\w\D])[\']([\w\D])', '\g<1> \'\g<2>', line) - # special case for "1990's" - line = re.sub(r'([\W\d])[\']([s])', '\g<1> \'\g<2>', line) - - # apply nonbreaking prefixes - words = line.split() - line = '' - for i in range(len(words)): - word = words[i] - match = re.search(r'^(\S+)\.$', word) - if match: - pre = match.group(1) - if i==len(words)-1: - # split last words independently as they are unlikely to be non-breaking prefixes - word = pre+' .' - elif ((re.search(r'\.', pre) and re.search(r'[^\.\W\d]', pre)) - or (pre in prefixes and prefixes[pre]==1) - or re.search(r'^[a-z]', words[i+1]) - or (pre in prefixes and prefixes[pre]==2 and re.search(r'^[0-9]+', words[i+1]))): - pass - else: - word = pre+' .' - - word +=' ' - line += word - - # clean up extraneous spaces - line = re.sub(' +', ' ', line) - line = re.sub('^ ', '', line) - line = re.sub(' $', '', line) - - # .' at end of sentence is missed - line = re.sub(r'\.\' ?$', ' . \' ', line) - - #restore multi-dots - while re.search('DOTDOTMULTI', line): - line = re.sub('DOTDOTMULTI', 'DOTMULTI.', line) - - line = re.sub('DOTMULTI', '.', line) - - # escape special characters - line = re.sub(r'\&', r'&', line) - line = re.sub(r'\|', r'|', line) - line = re.sub(r'\<', r'<', line) - line = re.sub(r'\>', r'>', line) - line = re.sub(r'\'', r''', line) - line = re.sub(r'\"', r'"', line) - line = re.sub(r'\[', r'[', line) - line = re.sub(r'\]', r']', line) - - #ensure final line breaks - if line[-1] != '\n': - line += '\n' - - return line - -def deescape(line): - line = re.sub(r'|', r'|', line) - line = re.sub(r'<', r'<', line) - line = re.sub(r'>', r'>', line) - line = re.sub(r'"', '\"', line) - line = re.sub(r''', '\'', line) - line = re.sub(r'[', r'[', line) - line = re.sub(r']', r']', line) - line = re.sub(r'&', r'&', line) - return line - - -class Tokenizer: - - @staticmethod - def add_file_to_dictionary(filename, dict, tokenize): - with open(filename, 'r') as f: - for line in f: - for word in tokenize(line).split(): - dict.add_symbol(word) - dict.add_symbol(dict.eos_word) - - @staticmethod - def binarize(filename, dict, consumer, tokenize=tokenize_line, - append_eos=True, reverse_order=False): - nseq, ntok = 0, 0 - replaced = Counter() - - def replaced_consumer(word, idx): - if idx == dict.unk_index and word != dict.unk_word: - replaced.update([word]) - - with open(filename, 'r') as f: - for line in f: - ids = Tokenizer.tokenize( - line=line, - dictionary=dict, - tokenize=tokenize, - add_if_not_exist=False, - consumer=replaced_consumer, - append_eos=append_eos, - reverse_order=reverse_order, - ) - nseq += 1 - - consumer(ids) - ntok += len(ids) - return {'nseq': nseq, 'nunk': sum(replaced.values()), 'ntok': ntok, 'replaced': len(replaced)} - - @staticmethod - def tokenize(line, dictionary, tokenize=tokenize_line, add_if_not_exist=True, - consumer=None, append_eos=True, reverse_order=False, bpe=None): - line = tokenize(line) - if bpe: - line = bpe.process_line(line) - words = line.split() - if reverse_order: - words = list(reversed(words)) - nwords = len(words) - ids = torch.IntTensor(nwords + 1 if append_eos else nwords) - - for i, word in enumerate(words): - if add_if_not_exist: - idx = dictionary.add_symbol(word) - else: - idx = dictionary.index(word) - if consumer is not None: - consumer(word, idx) - ids[i] = idx - if append_eos: - ids[nwords] = dictionary.eos_index - return ids - - @staticmethod - def detokenize(line, lang): - #don't try to detokenize XML/HTML tag lines - if re.search(r'^<.+>$', line) or re.search(r'^\s*$', line): - return line - - line = line.strip() - line = ' '+line+' ' - line = re.sub(r' @-@ ', '-', line) - line = deescape(line) - words = line.split() - line = '' - quote_count = {'\'':0, '\"':0} - prepend_space = ' ' - for i in range(len(words)): - #perform rught shift of currency and some punctuation - if re.search(r'^[\u20ac\x24\(\[\{]+$', words[i]): - line += prepend_space + words[i] - prepend_space = '' - elif re.search(r'^[\,\.\?\!\:\;\\\%\}\]\)]+$', words[i]): - if lang=='fr' and re.search(r'^[\?\!\:\;\\\%]$', words[i]): - line += ' ' - line += words[i] - prepend_space = ' ' - elif lang=='en' and i>0 and re.search(r'^[\'][\w\D]', words[i]) and re.search(r'\w$', words[i-1]): - line += words[i] - prepend_space = ' ' - elif lang=='cs' and i>1 and re.search(r'^\d+$', words[i-2]) and re.search(r'^[.,]$', words[i-1]) and re.search(r'^\w+$', words[i]): - line += words[i] - prepend_space = ' ' - elif (lang=='fr' or lang=='it') and i 0 and re.search(r'[s]$', words[i-1]): - #single quote for posessives ending in s... "The Jones' house" - #left shift - line += words[i] - prepend_space = ' ' - else: - #right shift - line += prepend_space + words[i] - prepend_space = '' - quote_count[normalized_quo] += 1 - else: - #left shift - line += words[i] - prepend_space = ' ' - quote_count[normalized_quo] += 1 - elif lang=='fi' and re.search(r':$', words[i-1]) and re.search(r'^(N|n|A|a|Ä|ä|ssa|Ssa|ssä|Ssä|sta|stä|Sta|Stä|hun|Hun|hyn|Hyn|han|Han|hän|Hän|hön|Hön|un|Un|yn|Yn|an|An|än|Än|ön|Ön|seen|Seen|lla|Lla|llä|Llä|lta|Lta|ltä|Ltä|lle|Lle|ksi|Ksi|kse|Kse|tta|Tta|ine|Ine)(ni|si|mme|nne|nsa)?(ko|kö|han|hän|pa|pä|kaan|kään|kin)?$', words[i]): - line += words[i].lower() - prepend_space = ' ' - else: - line += prepend_space + words[i] - prepend_space = ' ' - - #clean up spaces at head and tail of each line as well as any double-spacing - line = re.sub(r' +', ' ', line) - line = re.sub(r'\n ', '\n', line) - line = re.sub(r' \n', '\n', line) - line = re.sub(r'^ ', '', line) - line = re.sub(r' $', '', line) - - #add trailing break - line += '\n' if line[-1] != '\n' else '' - - return line diff --git a/PyTorch/NLP/Transformer/fairseq/utils.py b/PyTorch/NLP/Transformer/fairseq/utils.py deleted file mode 100644 index 52849aaf..00000000 --- a/PyTorch/NLP/Transformer/fairseq/utils.py +++ /dev/null @@ -1,316 +0,0 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#-------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from collections import defaultdict, OrderedDict -import logging -import os -import re -import torch -import traceback - -from torch.serialization import default_restore_location - - -def torch_persistent_save(*args, **kwargs): - for i in range(3): - try: - return torch.save(*args, **kwargs) - except Exception: - if i == 2: - logging.error(traceback.format_exc()) - - -def convert_state_dict_type(state_dict, ttype=torch.FloatTensor): - if isinstance(state_dict, dict): - cpu_dict = OrderedDict() - for k, v in state_dict.items(): - cpu_dict[k] = convert_state_dict_type(v) - return cpu_dict - elif isinstance(state_dict, list): - return [convert_state_dict_type(v) for v in state_dict] - elif torch.is_tensor(state_dict): - return state_dict.type(ttype) - else: - return state_dict - - -def save_state(filename, args, model, criterion, optimizer, lr_scheduler, - num_updates, optim_history=None, extra_state=None): - if optim_history is None: - optim_history = [] - if extra_state is None: - extra_state = {} - state_dict = { - 'args': args, - 'model': convert_state_dict_type(model.state_dict()), - 'optimizer_history': optim_history + [ - { - 'criterion_name': criterion.__class__.__name__, - 'optimizer_name': optimizer.__class__.__name__, - 'lr_scheduler_state': lr_scheduler.state_dict(), - 'num_updates': num_updates, - } - ], - 'last_optimizer_state': convert_state_dict_type(optimizer.state_dict()), - 'extra_state': extra_state, - } - torch_persistent_save(state_dict, filename) - - -def load_model_state(filename, model): - if not os.path.exists(filename): - return None, [], None - state = torch.load(filename, map_location=lambda s, l: default_restore_location(s, 'cpu')) - - # load model parameters - try: - model.load_state_dict(state['model'], strict=True) - except Exception: - raise Exception('Cannot load model parameters from checkpoint, ' - 'please ensure that the architectures match') - - return state['extra_state'], state['optimizer_history'], state['last_optimizer_state'] - - -def move_to_cuda(sample): - if len(sample) == 0: - return {} - - def _move_to_cuda(maybe_tensor): - if torch.is_tensor(maybe_tensor): - return maybe_tensor.cuda() - elif isinstance(maybe_tensor, dict): - return { - key: _move_to_cuda(value) - for key, value in maybe_tensor.items() - } - elif isinstance(maybe_tensor, list): - return [_move_to_cuda(x) for x in maybe_tensor] - else: - return maybe_tensor - - return _move_to_cuda(sample) - - -INCREMENTAL_STATE_INSTANCE_ID = defaultdict(lambda: 0) - - -def _get_full_incremental_state_key(module_instance, key): - module_name = module_instance.__class__.__name__ - - # assign a unique ID to each module instance, so that incremental state is - # not shared across module instances - if not hasattr(module_instance, '_fairseq_instance_id'): - INCREMENTAL_STATE_INSTANCE_ID[module_name] += 1 - module_instance._fairseq_instance_id = INCREMENTAL_STATE_INSTANCE_ID[module_name] - - return '{}.{}.{}'.format(module_name, module_instance._fairseq_instance_id, key) - - -def get_incremental_state(module, incremental_state, key): - """Helper for getting incremental state for an nn.Module.""" - full_key = _get_full_incremental_state_key(module, key) - if incremental_state is None or full_key not in incremental_state: - return None - return incremental_state[full_key] - - -def set_incremental_state(module, incremental_state, key, value): - """Helper for setting incremental state for an nn.Module.""" - if incremental_state is not None: - full_key = _get_full_incremental_state_key(module, key) - incremental_state[full_key] = value - - -def load_align_dict(replace_unk): - if replace_unk is None: - align_dict = None - elif isinstance(replace_unk, str): - # Load alignment dictionary for unknown word replacement if it was passed as an argument. - align_dict = {} - with open(replace_unk, 'r') as f: - for line in f: - cols = line.split() - align_dict[cols[0]] = cols[1] - else: - # No alignment dictionary provided but we still want to perform unknown word replacement by copying - # the original source word. - align_dict = {} - return align_dict - - -def print_embed_overlap(embed_dict, vocab_dict): - embed_keys = set(embed_dict.keys()) - vocab_keys = set(vocab_dict.symbols) - overlap = len(embed_keys & vocab_keys) - print("| Found {}/{} types in embedding file.".format(overlap, len(vocab_dict))) - - -def parse_embedding(embed_path): - """Parse embedding text file into a dictionary of word and embedding tensors. - - The first line can have vocabulary size and dimension. The following lines - should contain word and embedding separated by spaces. - - Example: - 2 5 - the -0.0230 -0.0264 0.0287 0.0171 0.1403 - at -0.0395 -0.1286 0.0275 0.0254 -0.0932 - """ - embed_dict = {} - with open(embed_path) as f_embed: - next(f_embed) # skip header - for line in f_embed: - pieces = line.rstrip().split(" ") - embed_dict[pieces[0]] = torch.Tensor([float(weight) for weight in pieces[1:]]) - return embed_dict - - -def load_embedding(embed_dict, vocab, embedding): - for idx in range(len(vocab)): - token = vocab[idx] - if token in embed_dict: - embedding.weight.data[idx] = embed_dict[token] - return embedding - - -def replace_unk(hypo_str, src_str, alignment, align_dict, unk): - from fairseq import tokenizer - # Tokens are strings here - hypo_tokens = tokenizer.tokenize_line(hypo_str) - # TODO: Very rare cases where the replacement is '' should be handled gracefully - src_tokens = tokenizer.tokenize_line(src_str) + [''] - for i, ht in enumerate(hypo_tokens): - if ht == unk: - src_token = src_tokens[alignment[i]] - # Either take the corresponding value in the aligned dictionary or just copy the original value. - hypo_tokens[i] = align_dict.get(src_token, src_token) - return ' '.join(hypo_tokens) - - -def post_process_prediction(hypo_tokens, src_str, alignment, align_dict, tgt_dict, remove_bpe): - from fairseq import tokenizer - hypo_str = tgt_dict.string(hypo_tokens, remove_bpe) - if align_dict is not None: - hypo_str = replace_unk(hypo_str, src_str, alignment, align_dict, tgt_dict.unk_string()) - if align_dict is not None or remove_bpe is not None: - # Convert back to tokens for evaluating with unk replacement or without BPE - # Note that the dictionary can be modified inside the method. - hypo_tokens = tokenizer.Tokenizer.tokenize(hypo_str, tgt_dict, add_if_not_exist=True) - return hypo_tokens, hypo_str, alignment - - -def make_positions(tensor, padding_idx, left_pad): - """Replace non-padding symbols with their position numbers. - - Position numbers begin at padding_idx+1. - - Padding symbols are ignored, but it is necessary to specify whether padding - is added on the left side (left_pad=True) or right side (left_pad=False). - """ - max_pos = padding_idx + 1 + tensor.size(1) - if not hasattr(make_positions, 'range_buf'): - make_positions.range_buf = torch.arange(padding_idx + 1, 768, - dtype=tensor.dtype, device=tensor.device) - make_positions.range_buf = make_positions.range_buf.type_as(tensor) - if make_positions.range_buf.numel() < max_pos: - torch.arange(padding_idx + 1, max_pos, out=make_positions.range_buf) - mask = tensor.ne(padding_idx) - positions = make_positions.range_buf[:tensor.size(1)].expand_as(tensor) - if left_pad: - positions = positions - mask.size(1) + mask.long().sum(dim=1).unsqueeze(1) - return tensor.clone().masked_scatter_(mask, positions[mask]) - - -def strip_pad(tensor, pad): - return tensor[tensor.ne(pad)] - - -def buffered_arange(max): - if not hasattr(buffered_arange, 'buf'): - buffered_arange.buf = torch.LongTensor() - if max > buffered_arange.buf.numel(): - torch.arange(max, out=buffered_arange.buf) - return buffered_arange.buf[:max] - - -def convert_padding_direction(src_tokens, padding_idx, right_to_left=False, left_to_right=False): - assert right_to_left ^ left_to_right - pad_mask = src_tokens.eq(padding_idx) - if not pad_mask.any(): - # no padding, return early - return src_tokens - if left_to_right and not pad_mask[:, 0].any(): - # already right padded - return src_tokens - if right_to_left and not pad_mask[:, -1].any(): - # already left padded - return src_tokens - max_len = src_tokens.size(1) - range = buffered_arange(max_len).type_as(src_tokens).expand_as(src_tokens) - num_pads = pad_mask.long().sum(dim=1, keepdim=True) - if right_to_left: - index = torch.remainder(range - num_pads, max_len) - else: - index = torch.remainder(range + num_pads, max_len) - return src_tokens.gather(1, index) - - -def item(tensor): - if hasattr(tensor, 'item'): - return tensor.item() - if hasattr(tensor, '__getitem__'): - return tensor[0] - return tensor - - -def clip_grad_norm_(tensor, max_norm): - grad_norm = item(torch.norm(tensor)) - if grad_norm > max_norm > 0: - clip_coef = max_norm / (grad_norm + 1e-6) - tensor.mul_(clip_coef) - return grad_norm - - -def fill_with_neg_inf(t): - """FP16-compatible function that fills a tensor with -inf.""" - return t.float().fill_(float('-inf')).type_as(t) - - -def checkpoint_paths(path, pattern=r'checkpoint(\d+)\.pt'): - """Retrieves all checkpoints found in `path` directory. - - Checkpoints are identified by matching filename to the specified pattern. If - the pattern contains groups, the result will be sorted by the first group in - descending order. - """ - pt_regexp = re.compile(pattern) - files = os.listdir(path) - - entries = [] - for i, f in enumerate(files): - m = pt_regexp.fullmatch(f) - if m is not None: - idx = int(m.group(1)) if len(m.groups()) > 0 else i - entries.append((idx, m.group(0))) - return [os.path.join(path, x[1]) for x in sorted(entries, reverse=True)] - diff --git a/PyTorch/NLP/Transformer/inference.py b/PyTorch/NLP/Transformer/inference.py deleted file mode 100644 index e34d42b7..00000000 --- a/PyTorch/NLP/Transformer/inference.py +++ /dev/null @@ -1,290 +0,0 @@ -#!/usr/bin/env python3 -u -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import sys -import os -import time -from collections import namedtuple - -import numpy as np -import torch -from torch.serialization import default_restore_location - -from fairseq import data, options, tokenizer, utils, log_helper -from fairseq.sequence_generator import SequenceGenerator -from fairseq.meters import StopwatchMeter -from fairseq.models.transformer import TransformerModel -import dllogger - -from apply_bpe import BPE - - -Batch = namedtuple('Batch', 'srcs tokens lengths') -Translation = namedtuple('Translation', 'src_str hypos pos_scores alignments') - - -def load_ensemble_for_inference(filenames): - """Load an ensemble of models for inference. - - model_arg_overrides allows you to pass a dictionary model_arg_overrides -- - {'arg_name': arg} -- to override model args that were used during model - training - """ - # load model architectures and weights - states = [] - for filename in filenames: - if not os.path.exists(filename): - raise IOError('Model file not found: {}'.format(filename)) - state = torch.load(filename, map_location=lambda s, l: default_restore_location(s, 'cpu')) - states.append(state) - - ensemble = [] - for state in states: - args = state['args'] - - # build model for ensemble - model = TransformerModel.build_model(args) - model.load_state_dict(state['model'], strict=True) - ensemble.append(model) - - src_dict = states[0]['extra_state']['src_dict'] - tgt_dict = states[0]['extra_state']['tgt_dict'] - - return ensemble, args, src_dict, tgt_dict - - -def buffered_read(buffer_size, data_descriptor): - buffer = [] - for src_str in data_descriptor: - buffer.append(src_str.strip()) - if len(buffer) >= buffer_size: - yield buffer - buffer = [] - - if buffer: - yield buffer - - -def make_batches(lines, args, src_dict, max_positions, bpe=None): - tokens = [ - tokenizer.Tokenizer.tokenize( - src_str, - src_dict, - tokenize=tokenizer.tokenize_en, - add_if_not_exist=False, - bpe=bpe - ).long() - for src_str in lines - ] - lengths = np.array([t.numel() for t in tokens]) - itr = data.EpochBatchIterator( - dataset=data.LanguagePairDataset(tokens, lengths, src_dict), - max_tokens=args.max_tokens, - max_sentences=args.max_sentences, - max_positions=max_positions, - ).next_epoch_itr(shuffle=False) - for batch in itr: - yield Batch( - srcs=[lines[i] for i in batch['id']], - tokens=batch['net_input']['src_tokens'], - lengths=batch['net_input']['src_lengths'], - ), batch['id'] - - -def setup_logger(args): - if not args.no_dllogger: - dllogger.init(backends=[dllogger.JSONStreamBackend(verbosity=1, filename=args.stat_file)]) - for k, v in vars(args).items(): - dllogger.log(step='PARAMETER', data={k:v}, verbosity=0) - container_setup_info = log_helper.get_framework_env_vars() - dllogger.log(step='PARAMETER', data=container_setup_info, verbosity=0) - dllogger.metadata('throughput', - {'unit':'tokens/s', 'format':':/3f', 'GOAL':'MAXIMIZE', 'STAGE':'INFER'}) - else: - dllogger.init(backends=[]) - - -def main(args): - setup_logger(args) - - args.interactive = sys.stdin.isatty() and not args.file # Just make the code more understendable - - if args.file: - data_descriptor = open(args.file, 'r') - else: - data_descriptor = sys.stdin - - if args.interactive: - args.buffer_size = 1 - if args.max_tokens is None and args.max_sentences is None: - args.max_sentences = 1 - if args.buffer_size > 50000: - print("WARNING: To prevent memory exhaustion buffer size is set to 50000", file=sys.stderr) - args.buffer_size = 50000 - - assert not args.sampling or args.nbest == args.beam, \ - '--sampling requires --nbest to be equal to --beam' - assert not args.max_sentences or args.max_sentences <= args.buffer_size, \ - '--max-sentences/--batch-size cannot be larger than --buffer-size' - - print(args, file=sys.stderr) - - use_cuda = torch.cuda.is_available() and not args.cpu - - processing_start = time.time() - - # Load ensemble - print('| loading model(s) from {}'.format(args.path), file=sys.stderr) - model_paths = args.path.split(':') - models, model_args, src_dict, tgt_dict = load_ensemble_for_inference(model_paths) - if args.fp16: - for model in models: - model.half() - - # Optimize ensemble for generation - for model in models: - model.make_generation_fast_(need_attn=args.print_alignment) - - # Initialize generator - translator = SequenceGenerator( - models, - tgt_dict.get_metadata(), - maxlen=args.max_target_positions, - beam_size=args.beam, - stop_early=(not args.no_early_stop), - normalize_scores=(not args.unnormalized), - len_penalty=args.lenpen, - unk_penalty=args.unkpen, - sampling=args.sampling, - sampling_topk=args.sampling_topk, - minlen=args.min_len, - sampling_temperature=args.sampling_temperature - ) - - if use_cuda: - translator.cuda() - - # Load BPE codes file - if args.bpe_codes: - codes = open(args.bpe_codes, 'r') - bpe = BPE(codes) - # Load alignment dictionary for unknown word replacement - # (None if no unknown word replacement, empty if no path to align dictionary) - align_dict = utils.load_align_dict(args.replace_unk) - - def make_result(src_str, hypos): - result = Translation( - src_str=src_str, - hypos=[], - pos_scores=[], - alignments=[], - ) - - # Process top predictions - for hypo in hypos[:min(len(hypos), args.nbest)]: - hypo_tokens, hypo_str, alignment = utils.post_process_prediction( - hypo_tokens=hypo['tokens'].int().cpu(), - src_str=src_str, - alignment=hypo['alignment'].int().cpu() if hypo['alignment'] is not None else None, - align_dict=align_dict, - tgt_dict=tgt_dict, - remove_bpe=args.remove_bpe, - ) - hypo_str = tokenizer.Tokenizer.detokenize(hypo_str, 'de').strip() - result.hypos.append((hypo['score'], hypo_str)) - result.pos_scores.append('P\t' + ' '.join(f'{x:.4f}' for x in hypo['positional_scores'].tolist())) - result.alignments.append('A\t' + ' '.join(str(utils.item(x)) for x in alignment) - if args.print_alignment else None - ) - - return result - - gen_timer = StopwatchMeter() - - def process_batch(batch): - tokens = batch.tokens - lengths = batch.lengths - - if use_cuda: - tokens = tokens.cuda() - lengths = lengths.cuda() - - translation_start = time.time() - gen_timer.start() - translations = translator.generate( - tokens, - lengths, - maxlen=int(args.max_len_a * tokens.size(1) + args.max_len_b), - ) - gen_timer.stop(sum(len(h[0]['tokens']) for h in translations)) - dllogger.log(step='infer', data={'latency': time.time() - translation_start}) - - return [make_result(batch.srcs[i], t) for i, t in enumerate(translations)] - - if args.interactive: - print('| Type the input sentence and press return:') - for inputs in buffered_read(args.buffer_size, data_descriptor): - indices = [] - results = [] - for batch, batch_indices in make_batches(inputs, args, src_dict, args.max_positions, bpe): - indices.extend(batch_indices) - results += process_batch(batch) - - for i in np.argsort(indices): - result = results[i] - print(result.src_str, file=sys.stderr) - for hypo, pos_scores, align in zip(result.hypos, result.pos_scores, result.alignments): - print(f'Score {hypo[0]}', file=sys.stderr) - print(hypo[1]) - print(pos_scores, file=sys.stderr) - if align is not None: - print(align, file=sys.stderr) - - if args.file: - data_descriptor.close() - - log_dict = { - 'throughput': 1./gen_timer.avg, - 'latency_avg': sum(gen_timer.intervals)/len(gen_timer.intervals), - 'latency_p90': gen_timer.p(90), - 'latency_p95': gen_timer.p(95), - 'latency_p99': gen_timer.p(99), - 'total_infernece_time': gen_timer.sum, - 'total_run_time': time.time() - processing_start, - } - print('Translation time: {} s'.format(log_dict['total_infernece_time']), - file=sys.stderr) - print('Model throughput (beam {}): {} tokens/s'.format(args.beam, log_dict['throughput']), - file=sys.stderr) - print('Latency:\n\tAverage {:.3f}s\n\tp90 {:.3f}s\n\tp95 {:.3f}s\n\tp99 {:.3f}s'.format( - log_dict['latency_avg'], log_dict['latency_p90'], log_dict['latency_p95'], log_dict['latency_p99']), - file=sys.stderr) - print('End to end time: {} s'.format(log_dict['total_run_time']), file=sys.stderr) - dllogger.log(step=(), data=log_dict) - - -if __name__ == '__main__': - parser = options.get_inference_parser() - parser.add_argument('--no-dllogger', action='store_true') - ARGS = options.parse_args_and_arch(parser) - main(ARGS) diff --git a/PyTorch/NLP/Transformer/preprocess.py b/PyTorch/NLP/Transformer/preprocess.py deleted file mode 100644 index 4626fa04..00000000 --- a/PyTorch/NLP/Transformer/preprocess.py +++ /dev/null @@ -1,210 +0,0 @@ -#!/usr/bin/env python3 -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# - -import argparse -from itertools import zip_longest -import os -import shutil - -from fairseq.data import indexed_dataset, dictionary -from fairseq.tokenizer import Tokenizer, tokenize_line - - -def get_parser(): - parser = argparse.ArgumentParser( - description='Data pre-processing: Create dictionary and store data in binary format') - parser.add_argument('-s', '--source-lang', default=None, metavar='SRC', - help='source language') - parser.add_argument('-t', '--target-lang', default=None, metavar='TARGET', - help='target language') - parser.add_argument('--trainpref', metavar='FP', default=None, - help='train file prefix') - parser.add_argument('--validpref', metavar='FP', default=None, - help='comma separated, valid file prefixes') - parser.add_argument('--testpref', metavar='FP', default=None, - help='comma separated, test file prefixes') - parser.add_argument('--destdir', metavar='DIR', default='data-bin', - help='destination dir') - parser.add_argument('--thresholdtgt', metavar='N', default=0, type=int, - help='map words appearing less than threshold times to unknown') - parser.add_argument('--thresholdsrc', metavar='N', default=0, type=int, - help='map words appearing less than threshold times to unknown') - parser.add_argument('--tgtdict', metavar='FP', help='reuse given target dictionary') - parser.add_argument('--srcdict', metavar='FP', help='reuse given source dictionary') - parser.add_argument('--nwordstgt', metavar='N', default=-1, type=int, - help='number of target words to retain') - parser.add_argument('--nwordssrc', metavar='N', default=-1, type=int, - help='number of source words to retain') - parser.add_argument('--alignfile', metavar='ALIGN', default=None, - help='an alignment file (optional)') - parser.add_argument('--output-format', metavar='FORMAT', default='binary', choices=['binary', 'raw'], - help='output format (optional)') - parser.add_argument('--joined-dictionary', action='store_true', help='Generate joined dictionary') - parser.add_argument('--only-source', action='store_true', help='Only process the source language') - parser.add_argument('--padding-factor', metavar='N', default=8, type=int, - help='Pad dictionary size to be multiple of N') - return parser - - -def main(args): - print(args) - os.makedirs(args.destdir, exist_ok=True) - target = not args.only_source - - def build_dictionary(filenames): - d = dictionary.Dictionary() - for filename in filenames: - Tokenizer.add_file_to_dictionary(filename, d, tokenize_line) - return d - - def train_path(lang): - return '{}{}'.format(args.trainpref, ('.' + lang) if lang else '') - - def file_name(prefix, lang): - fname = prefix - if lang is not None: - fname += f'.{lang}' - return fname - - def dest_path(prefix, lang): - return os.path.join(args.destdir, file_name(prefix, lang)) - - def dict_path(lang): - return dest_path('dict', lang) + '.txt' - - def dataset_dest_path(output_prefix, lang, extension): - base = f'{args.destdir}/{output_prefix}' - lang_part = f'.{args.source_lang}-{args.target_lang}.{lang}' if lang is not None else '' - return f'{base}{lang_part}.{extension}' - - if args.joined_dictionary: - assert not args.srcdict, 'cannot combine --srcdict and --joined-dictionary' - assert not args.tgtdict, 'cannot combine --tgtdict and --joined-dictionary' - src_dict = build_dictionary({ - train_path(lang) - for lang in [args.source_lang, args.target_lang] - }) - tgt_dict = src_dict - else: - if args.srcdict: - src_dict = dictionary.Dictionary.load(args.srcdict) - else: - assert args.trainpref, "--trainpref must be set if --srcdict is not specified" - src_dict = build_dictionary([train_path(args.source_lang)]) - if target: - if args.tgtdict: - tgt_dict = dictionary.Dictionary.load(args.tgtdict) - else: - assert args.trainpref, "--trainpref must be set if --tgtdict is not specified" - tgt_dict = build_dictionary([train_path(args.target_lang)]) - - src_dict.finalize( - threshold=args.thresholdsrc, - nwords=args.nwordssrc, - padding_factor=args.padding_factor, - ) - src_dict.save(dict_path(args.source_lang)) - if target: - if not args.joined_dictionary: - tgt_dict.finalize( - threshold=args.thresholdtgt, - nwords=args.nwordstgt, - padding_factor=args.padding_factor, - ) - tgt_dict.save(dict_path(args.target_lang)) - - def make_binary_dataset(input_prefix, output_prefix, lang): - _dict = dictionary.Dictionary.load(dict_path(lang)) - print('| [{}] Dictionary: {} types'.format(lang, len(_dict) - 1)) - - ds = indexed_dataset.IndexedDatasetBuilder(dataset_dest_path(output_prefix, lang, 'bin')) - - def consumer(tensor): - ds.add_item(tensor) - - input_file = '{}{}'.format(input_prefix, ('.' + lang) if lang is not None else '') - res = Tokenizer.binarize(input_file, _dict, consumer) - print('| [{}] {}: {} sents, {} tokens, {:.3}% replaced by {}'.format( - lang, input_file, res['nseq'], res['ntok'], - 100 * res['nunk'] / res['ntok'], _dict.unk_word)) - ds.finalize(dataset_dest_path(output_prefix, lang, 'idx')) - - def make_dataset(input_prefix, output_prefix, lang): - if args.output_format == 'binary': - make_binary_dataset(input_prefix, output_prefix, lang) - elif args.output_format == 'raw': - # Copy original text file to destination folder - output_text_file = dest_path( - output_prefix + '.{}-{}'.format(args.source_lang, args.target_lang), - lang, - ) - shutil.copyfile(file_name(input_prefix, lang), output_text_file) - - def make_all(lang): - if args.trainpref: - make_dataset(args.trainpref, 'train', lang) - if args.validpref: - for k, validpref in enumerate(args.validpref.split(',')): - outprefix = 'valid{}'.format(k) if k > 0 else 'valid' - make_dataset(validpref, outprefix, lang) - if args.testpref: - for k, testpref in enumerate(args.testpref.split(',')): - outprefix = 'test{}'.format(k) if k > 0 else 'test' - make_dataset(testpref, outprefix, lang) - - make_all(args.source_lang) - if target: - make_all(args.target_lang) - - print('| Wrote preprocessed data to {}'.format(args.destdir)) - - if args.alignfile: - assert args.trainpref, "--trainpref must be set if --alignfile is specified" - src_file_name = train_path(args.source_lang) - tgt_file_name = train_path(args.target_lang) - src_dict = dictionary.Dictionary.load(dict_path(args.source_lang)) - tgt_dict = dictionary.Dictionary.load(dict_path(args.target_lang)) - freq_map = {} - with open(args.alignfile, 'r') as align_file: - with open(src_file_name, 'r') as src_file: - with open(tgt_file_name, 'r') as tgt_file: - for a, s, t in zip_longest(align_file, src_file, tgt_file): - si = Tokenizer.tokenize(s, src_dict, add_if_not_exist=False) - ti = Tokenizer.tokenize(t, tgt_dict, add_if_not_exist=False) - ai = list(map(lambda x: tuple(x.split('-')), a.split())) - for sai, tai in ai: - srcidx = si[int(sai)] - tgtidx = ti[int(tai)] - if srcidx != src_dict.unk() and tgtidx != tgt_dict.unk(): - assert srcidx != src_dict.pad() - assert srcidx != src_dict.eos() - assert tgtidx != tgt_dict.pad() - assert tgtidx != tgt_dict.eos() - - if srcidx not in freq_map: - freq_map[srcidx] = {} - if tgtidx not in freq_map[srcidx]: - freq_map[srcidx][tgtidx] = 1 - else: - freq_map[srcidx][tgtidx] += 1 - - align_dict = {} - for srcidx in freq_map: - align_dict[srcidx] = max(freq_map[srcidx], key=freq_map[srcidx].get) - - with open(os.path.join(args.destdir, 'alignment.{}-{}.txt'.format( - args.source_lang, args.target_lang)), 'w') as f: - for k, v in align_dict.items(): - print('{} {}'.format(src_dict[k], tgt_dict[v]), file=f) - - -if __name__ == '__main__': - parser = get_parser() - ARGS = parser.parse_args() - main(ARGS) diff --git a/PyTorch/NLP/Transformer/requirements.txt b/PyTorch/NLP/Transformer/requirements.txt deleted file mode 100644 index b679dae5..00000000 --- a/PyTorch/NLP/Transformer/requirements.txt +++ /dev/null @@ -1,5 +0,0 @@ -cffi -numpy -torch -tqdm -tensorboardX diff --git a/PyTorch/NLP/Transformer/scripts/average_checkpoints.py b/PyTorch/NLP/Transformer/scripts/average_checkpoints.py deleted file mode 100644 index 58929f72..00000000 --- a/PyTorch/NLP/Transformer/scripts/average_checkpoints.py +++ /dev/null @@ -1,137 +0,0 @@ -#!/usr/bin/env python3 - -import argparse -import collections -import torch -import os -import re - - -def average_checkpoints(inputs): - """Loads checkpoints from inputs and returns a model with averaged weights. - - Args: - inputs: An iterable of string paths of checkpoints to load from. - - Returns: - A dict of string keys mapping to various values. The 'model' key - from the returned dict should correspond to an OrderedDict mapping - string parameter names to torch Tensors. - """ - params_dict = collections.OrderedDict() - params_keys = None - new_state = None - for f in inputs: - state = torch.load( - f, - map_location=( - lambda s, _: torch.serialization.default_restore_location(s, 'cpu') - ), - ) - # Copies over the settings from the first checkpoint - if new_state is None: - new_state = state - - model_params = state['model'] - - model_params_keys = list(model_params.keys()) - if params_keys is None: - params_keys = model_params_keys - elif params_keys != model_params_keys: - raise KeyError( - 'For checkpoint {}, expected list of params: {}, ' - 'but found: {}'.format(f, params_keys, model_params_keys) - ) - - for k in params_keys: - if k not in params_dict: - params_dict[k] = [] - p = model_params[k] - if isinstance(p, torch.HalfTensor): - p = p.float() - params_dict[k].append(p) - - averaged_params = collections.OrderedDict() - # v should be a list of torch Tensor. - for k, v in params_dict.items(): - summed_v = None - for x in v: - summed_v = summed_v + x if summed_v is not None else x - averaged_params[k] = summed_v / len(v) - new_state['model'] = averaged_params - return new_state - - -def last_n_checkpoints(paths, n, update_based): - assert len(paths) == 1 - path = paths[0] - if update_based: - pt_regexp = re.compile(r'checkpoint_\d+_(\d+)\.pt') - else: - pt_regexp = re.compile(r'checkpoint(\d+)\.pt') - files = os.listdir(path) - - entries = [] - for f in files: - m = pt_regexp.fullmatch(f) - if m is not None: - entries.append((int(m.group(1)), m.group(0))) - if len(entries) < n: - raise Exception('Found {} checkpoint files but need at least {}', len(entries), n) - return [os.path.join(path, x[1]) for x in sorted(entries, reverse=True)[:n]] - - -def main(): - parser = argparse.ArgumentParser( - description='Tool to average the params of input checkpoints to ' - 'produce a new checkpoint', - ) - - parser.add_argument( - '--inputs', - required=True, - nargs='+', - help='Input checkpoint file paths.', - ) - parser.add_argument( - '--output', - required=True, - metavar='FILE', - help='Write the new checkpoint containing the averaged weights to this ' - 'path.', - ) - num_group = parser.add_mutually_exclusive_group() - num_group.add_argument( - '--num-epoch-checkpoints', - type=int, - help='if set, will try to find checkpoints with names checkpoint_xx.pt in the path specified by input, ' - 'and average last this many of them.', - ) - num_group.add_argument( - '--num-update-checkpoints', - type=int, - help='if set, will try to find checkpoints with names checkpoint_ee_xx.pt in the path specified by input, ' - 'and average last this many of them.', - ) - args = parser.parse_args() - print(args) - - num = None - is_update_based = False - if args.num_update_checkpoints is not None: - num = args.num_update_checkpoints - is_update_based = True - elif args.num_epoch_checkpoints is not None: - num = args.num_epoch_checkpoints - - if num is not None: - args.inputs = last_n_checkpoints(args.inputs, num, is_update_based) - print('averaging checkpoints: ', args.inputs) - - new_state = average_checkpoints(args.inputs) - torch.save(new_state, args.output) - print('Finished writing averaged checkpoint to {}.'.format(args.output)) - - -if __name__ == '__main__': - main() diff --git a/PyTorch/NLP/Transformer/scripts/deployer.py b/PyTorch/NLP/Transformer/scripts/deployer.py deleted file mode 100644 index 261b96ad..00000000 --- a/PyTorch/NLP/Transformer/scripts/deployer.py +++ /dev/null @@ -1,123 +0,0 @@ -#!/usr/bin/python - -# Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - - -import sys -import torch -import argparse -import deployer_lib -# -import torch -from fairseq import data -from fairseq.data import load_dataset_splits, data_utils -from fairseq.models.transformer import TransformerModel -from copy import deepcopy - -def get_model_and_args(model_args): - ''' the arguments initialize_model will receive ''' - parser = argparse.ArgumentParser() - ## Required parameters by the model. - parser.add_argument("--checkpoint", - default=None, - type=str, - required=True, - help="The checkpoint of the model. ") - parser.add_argument('--batch-size', - default=10240, - type=int, - help='Batch size for inference') - parser.add_argument('--num-batches', - default=2, - type=int, - help='Number of batches to check accuracy on') - parser.add_argument("--data", - default=None, - type=str, - required=True, - help="Path to the dataset") - parser.add_argument('--part', - choices=['encoder', 'decoder', 'model'], - default='model', - type=str, - help='Choose the part of the model to export') - - args = parser.parse_args(model_args) - - state_dict = torch.load(args.checkpoint, map_location='cpu') - - model_args = state_dict['args'] - model_args.data = args.data - model_args.num_batches = args.num_batches - model_args.max_tokens = args.batch_size - model_args.fuse_layer_norm = False - model_args.part = args.part - - model = TransformerModel.build_model(model_args) - model.load_state_dict(state_dict['model'], strict=True) - model.make_generation_fast_(need_attn=False) - - return model, model_args - -def get_dataloader(args, encoder=None): - ''' return dataloader for inference ''' - assert not(args.part == 'decoder' and encoder is None), "Cannot export decoder without providing encoder" - src_dict, tgt_dict = data_utils.load_dictionaries(args) - datasets = load_dataset_splits(args, ['valid'], src_dict, tgt_dict) - itr = data.EpochBatchIterator( - dataset=datasets['valid'], - max_tokens=args.max_tokens, - max_positions=args.max_positions, - ).next_epoch_itr(shuffle=False) - - def input_itr(): - for batch in itr: - if itr.count > args.num_batches: - break - ni = batch['net_input'] - if args.part == 'decoder': #this part works only on GPU - with torch.no_grad(): - encoder_out = encoder(ni['src_tokens'].cuda(), ni['src_lengths'].cuda()) - yield ni['prev_output_tokens'], encoder_out[0], encoder_out[1] - elif args.part == 'encoder': - yield ni['src_tokens'], ni['src_lengths'] - else: - yield ni['src_tokens'], ni['src_lengths'], ni['prev_output_tokens'] - - return input_itr() - - -if __name__=='__main__': - # don't touch this! - deployer, model_argv = deployer_lib.create_deployer(sys.argv[1:]) # deployer and returns removed deployer arguments - - model, model_args = get_model_and_args(model_argv) - - if model_args.part == 'decoder': - encoder = model.encoder - encoder.embed_tokens = deepcopy(encoder.embed_tokens) - encoder.cuda() - else: - encoder = None - - dataloader = get_dataloader(model_args, encoder=encoder) - - if model_args.part == 'encoder': - model = model.encoder - elif model_args.part == 'decoder': - model = model.decoder - - deployer.deploy(dataloader, model) - diff --git a/PyTorch/NLP/Transformer/scripts/deployer_lib.py b/PyTorch/NLP/Transformer/scripts/deployer_lib.py deleted file mode 100644 index 8cb93f1e..00000000 --- a/PyTorch/NLP/Transformer/scripts/deployer_lib.py +++ /dev/null @@ -1,969 +0,0 @@ -#!/usr/bin/python - -# Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - - -import os -import sys -import time -import json -import torch -import argparse -import statistics -from collections import Counter - - -torch_type_to_triton_type = { - torch.bool: 'TYPE_BOOL', - torch.int8: 'TYPE_INT8', - torch.int16: 'TYPE_INT16', - torch.int32: 'TYPE_INT32', - torch.int64: 'TYPE_INT64', - torch.uint8: 'TYPE_UINT8', - torch.float16: 'TYPE_FP16', - torch.float32: 'TYPE_FP32', - torch.float64: 'TYPE_FP64' -} - - -CONFIG_TEMPLATE = r""" -name: "{model_name}" -platform: "{platform}" -max_batch_size: {max_batch_size} -input [ - {spec_inputs} -] -output [ - {spec_outputs} -] -{dynamic_batching} -{model_optimizations} -instance_group [ - {{ - count: {engine_count} - kind: KIND_GPU - gpus: [ {gpu_list} ] - }} -]""" - - -INPUT_TEMPLATE = r""" -{{ - name: "input__{num}" - data_type: {type} - dims: {dims} - {reshape} -}},""" - - -OUTPUT_TEMPLATE = r""" -{{ - name: "output__{num}" - data_type: {type} - dims: {dims} - {reshape} -}},""" - - -MODEL_OPTIMIZATION_TEMPLATE = r""" -optimization {{ - {execution_accelerator} - cuda {{ - graphs: {capture_cuda_graph} - }} -}}""" - - -EXECUTION_ACCELERATOR_TEMPLATE = r""" - execution_accelerators {{ - gpu_execution_accelerator: [ - {{ - name: "tensorrt" - }} - ] - }},""" - - -def remove_empty_lines(text): - ''' removes empty lines from text, returns the result ''' - ret = "".join([s for s in text.strip().splitlines(True) if s.strip()]) - return ret - - -def create_deployer(argv): - ''' takes a list of arguments, returns a deployer object and the list of unused arguments ''' - parser = argparse.ArgumentParser() - # required args - method = parser.add_mutually_exclusive_group(required=True) - method.add_argument('--ts-script', - action='store_true', - help='convert to torchscript using torch.jit.script') - method.add_argument('--ts-trace', - action='store_true', - help='convert to torchscript using torch.jit.trace') - method.add_argument('--onnx', - action='store_true', - help='convert to onnx using torch.onnx.export') - method.add_argument('--trt', - action='store_true', - help='convert to trt using tensorrt') - # triton related args - arguments = parser.add_argument_group('triton related flags') - arguments.add_argument('--triton-no-cuda', - action='store_true', - help='Use the CPU for tracing.') - arguments.add_argument('--triton-model-name', - type=str, - default="model", - help="exports to appropriate directory structure for TRTIS") - arguments.add_argument("--triton-model-version", - type=int, - default=1, - help="exports to appropriate directory structure for TRTIS") - arguments.add_argument("--triton-server-url", - type=str, - default="localhost:8001", - help="exports to appropriate directory structure for TRTIS") - arguments.add_argument("--triton-max-batch-size", - type=int, - default=8, - help="Specifies the 'max_batch_size' in the TRTIS model config.\ - See the TRTIS documentation for more info.") - arguments.add_argument("--triton-dyn-batching-delay", - type=float, - default=0, - help="Determines the dynamic_batching queue delay in milliseconds(ms) for\ - the TRTIS model config. Use '0' or '-1' to specify static batching.\ - See the TRTIS documentation for more info.") - arguments.add_argument("--triton-engine-count", - type=int, - default=1, - help="Specifies the 'instance_group' count value in the TRTIS model config.\ - See the TRTIS documentation for more info.") - arguments.add_argument('--save-dir', type=str, default='./triton_models', help='Saved model directory') - # optimization args - arguments = parser.add_argument_group('optimization flags') - arguments.add_argument("--max_workspace_size", - type=int, - default=512*1024*1024, - help="set the size of the workspace for trt export") - arguments.add_argument("--trt-fp16", - action='store_true', - help="trt flag ---- export model in mixed precision mode") - arguments.add_argument("--capture-cuda-graph", - type=int, - default=1, - help="capture cuda graph for obtaining speedup. possible values: 0, 1. default: 1. ") - arguments.add_argument('--quantize', - action='store_true', - help='apply quantization for supported nodes') - arguments.add_argument('--calibrate', - action='store_true', - help='apply calibration for supported nodes') - # remainder args - arguments.add_argument('model_arguments', nargs=argparse.REMAINDER, help='arguments that will be ignored by deployer lib and will be forwarded to your deployer script') - # - args = parser.parse_args(argv) - deployer = Deployer(args) - # - return deployer, args.model_arguments[1:] - - -class DeployerLibrary: - def __init__(self, args): - self.args = args - self.platform = None - - def set_platform(self, platform): - ''' sets the platform - :: platform :: "pytorch_libtorch" or "onnxruntime_onnx" or "tensorrt_plan" - ''' - self.platform = platform - - def build_trt_engine(self, model_file, shapes): - ''' takes a path to an onnx file, and shape information, returns a trt engine - :: model_file :: path to an onnx model - :: shapes :: dictionary containing min shape, max shape, opt shape for the trt engine - ''' - import tensorrt as trt - TRT_LOGGER = trt.Logger(trt.Logger.WARNING) - builder = trt.Builder(TRT_LOGGER) - builder.fp16_mode = self.args.trt_fp16 - builder.max_batch_size = self.args.triton_max_batch_size - # - config = builder.create_builder_config() - config.max_workspace_size = self.args.max_workspace_size - if self.args.trt_fp16: - config.flags |= 1 << int(trt.BuilderFlag.FP16) - profile = builder.create_optimization_profile() - for s in shapes: - profile.set_shape(s['name'], min=s['min'], opt=s['opt'], max=s['max']) - config.add_optimization_profile(profile) - explicit_batch = 1 << (int)(trt.NetworkDefinitionCreationFlag.EXPLICIT_BATCH) - network = builder.create_network(explicit_batch) - # - with trt.OnnxParser(network, TRT_LOGGER) as parser: - with open(model_file, 'rb') as model: - parser.parse(model.read()) - for i in range(parser.num_errors): - e = parser.get_error(i) - print("||||e", e) - engine = builder.build_engine(network, config=config) - return engine - - def load_engine(self, engine_filepath): - ''' loads a trt engine from engine_filepath, returns it ''' - import tensorrt as trt - TRT_LOGGER = trt.Logger(trt.Logger.WARNING) - with open(engine_filepath, "rb") as f, trt.Runtime(TRT_LOGGER) as runtime: - engine = runtime.deserialize_cuda_engine(f.read()) - return engine - - def prepare_inputs(self, dataloader, device): - ''' load sample inputs to device ''' - def _move_to_device(maybe_tensor): - if torch.is_tensor(maybe_tensor): - return maybe_tensor.to(device) - elif isinstance(maybe_tensor, dict): - return { - key: _move_to_device(value) - for key, value in maybe_tensor.items() - } - elif isinstance(maybe_tensor, list) or isinstance(maybe_tensor, tuple): - return [_move_to_device(x) for x in maybe_tensor] - else: - return maybe_tensor - - inputs = [] - for batch in dataloader: - batch_d = _move_to_device(batch) - if not hasattr(batch_d, '__iter__'): - batch_d = (batch_d,) - inputs.append(batch_d) - - return inputs - - def get_list_of_shapes(self, l, fun): - ''' returns the list of min/max shapes, depending on fun - :: l :: list of tuples of tensors - :: fun :: min or max - ''' - tensor_tuple = l[0] - shapes = [list(x.shape) for x in tensor_tuple] - for tensor_tuple in l: - assert len(tensor_tuple) == len(shapes), "tensors with varying shape lengths are not supported" - for i,x in enumerate(tensor_tuple): - for j in range(len(x.shape)): - shapes[i][j] = fun(shapes[i][j], x.shape[j]) - return shapes # a list of shapes - - def get_tuple_of_min_shapes(self, l): - ''' returns the tuple of min shapes - :: l :: list of tuples of tensors ''' - shapes = self.get_list_of_shapes(l, min) - min_batch = 1 - shapes = [[min_batch,*shape[1:]] for shape in shapes] - shapes = tuple(shapes) - return shapes # tuple of min shapes - - def get_tuple_of_max_shapes(self, l): - ''' returns the tuple of max shapes - :: l :: list of tuples of tensors ''' - shapes = self.get_list_of_shapes(l, max) - max_batch = max(2,shapes[0][0]) - shapes = [[max_batch,*shape[1:]] for shape in shapes] - shapes = tuple(shapes) - return shapes # tuple of max shapes - - def get_tuple_of_opt_shapes(self, l): - ''' returns the tuple of opt shapes - :: l :: list of tuples of tensors ''' - counter = Counter() - for tensor_tuple in l: - shapes = [tuple(x.shape) for x in tensor_tuple] - shapes = tuple(shapes) - counter[shapes] += 1 - shapes = counter.most_common(1)[0][0] - return shapes # tuple of most common occuring shapes - - def get_tuple_of_dynamic_shapes(self, l): - ''' returns a tuple of dynamic shapes: variable tensor dimensions - (for ex. batch size) occur as -1 in the tuple - :: l :: list of tuples of tensors ''' - tensor_tuple = l[0] - shapes = [list(x.shape) for x in tensor_tuple] - for tensor_tuple in l: - err_msg = "tensors with varying shape lengths are not supported" - assert len(tensor_tuple) == len(shapes), err_msg - for i,x in enumerate(tensor_tuple): - for j in range(len(x.shape)): - if shapes[i][j] != x.shape[j] or j == 0: - shapes[i][j] = -1 - shapes = tuple(shapes) - return shapes # tuple of dynamic shapes - - def run_models(self, models, inputs): - ''' run the models on inputs, return the outputs and execution times ''' - ret = [] - for model in models: - torch.cuda.synchronize() - time_start = time.time() - outputs = [] - for input in inputs: - with torch.no_grad(): - output = model(*input) - if type(output) is torch.Tensor: - output = [output] - elif type(output) is dict: - output = list(output.items()) - output.sort(key=lambda x: x[0]) - output = [x[0] for x in output] - outputs.append(output) - torch.cuda.synchronize() - time_end = time.time() - t = time_end - time_start - ret.append(outputs) - ret.append(t) - return ret - - def compute_tensor_stats(self, tensor): - #if tensor is not empty - if tensor.numel(): - return {'std': tensor.std().item(), - 'mean': tensor.mean().item(), - 'max': tensor.max().item(), - 'min': tensor.min().item(), - } - else: - return {'std': 0, - 'mean':0, - 'max': 0, - 'min': 0, - } - - def compute_errors(self, outputs_A, outputs_B): - ''' returns dictionary with errors statistics ''' - device = outputs_A[0][0][0].device - dtype = outputs_A[0][0][0].dtype - num_outputs = len(outputs_A[0]) - x_values = [torch.zeros(0, device = device, dtype = dtype) for _ in range(num_outputs)] - y_values = [torch.zeros(0, device = device, dtype = dtype) for _ in range(num_outputs)] - d_values = [torch.zeros(0, device = device, dtype = dtype) for _ in range(num_outputs)] - for output_A,output_B in zip(outputs_A,outputs_B): - for i,(x,y) in enumerate(zip(output_A, output_B)): - x = x.view(-1).float() - y = y.view(-1).float() - d = abs(x - y) - x_values[i] = torch.cat((x_values[i], x), 0) - y_values[i] = torch.cat((y_values[i], y), 0) - d_values[i] = torch.cat((d_values[i], d), 0) - Error_stats = [{'Original': self.compute_tensor_stats(x), - 'Converted': self.compute_tensor_stats(y), - 'Absolute difference': self.compute_tensor_stats(d), - } for x,y,z in zip(x_values, y_values, d_values)] - return Error_stats - - def print_errors(self, Error_stats): - ''' print various statistcs of Linf errors ''' - print() - print("conversion correctness test results") - print("-----------------------------------") - import pandas as pd - for i,e in enumerate(Error_stats): - print(f'Output {i}:') - print(pd.DataFrame(e)) - - def write_config(self, config_filename, - input_shapes, input_types, - output_shapes, output_types): - ''' writes TRTIS config file - :: config_filename :: the file to write the config file into - :: input_shapes :: tuple of dynamic shapes of the input tensors - :: input_types :: tuple of torch types of the input tensors - :: output_shapes :: tuple of dynamic shapes of the output tensors - :: output_types :: tuple of torch types of the output tensors - ''' - assert self.platform is not None, "error - platform is not set" - - config_template = CONFIG_TEMPLATE - input_template = INPUT_TEMPLATE - optimization_template = MODEL_OPTIMIZATION_TEMPLATE - accelerator_template = EXECUTION_ACCELERATOR_TEMPLATE - - spec_inputs = r"""""" - for i,(shape,typ) in enumerate(zip(input_shapes,input_types)): - d = { - 'num' : str(i), - 'type': torch_type_to_triton_type[typ], - 'dims': str([1]) if len(shape) == 1 else str(list(shape)[1:]) # first dimension is the batch size - } - d['reshape'] = 'reshape: { shape: [ ] }' if len(shape) == 1 else '' - spec_inputs += input_template.format_map(d) - spec_inputs = spec_inputs[:-1] - - output_template = OUTPUT_TEMPLATE - spec_outputs = r"""""" - for i,(shape,typ) in enumerate(zip(output_shapes,output_types)): - d = { - 'num' : str(i), - 'type': torch_type_to_triton_type[typ], - 'dims': str([1]) if len(shape) == 1 else str(list(shape)[1:]) # first dimension is the batch size - } - d['reshape'] = 'reshape: { shape: [ ] }' if len(shape) == 1 else '' - spec_outputs += output_template.format_map(d) - spec_outputs = spec_outputs[:-1] - - batching_str = "" - max_batch_size = self.args.triton_max_batch_size - - if (self.args.triton_dyn_batching_delay > 0): - # Use only full and half full batches - pref_batch_size = [int(max_batch_size / 2.0), max_batch_size] - - batching_str = r""" -dynamic_batching {{ - preferred_batch_size: [{0}] - max_queue_delay_microseconds: {1} -}}""".format(", ".join([str(x) for x in pref_batch_size]), - int(self.args.triton_dyn_batching_delay * 1000.0)) - - accelerator_str = "" - if self.platform == 'onnxruntime_onnx': - accelerator_str = accelerator_template.format_map({}) - - d = { - "execution_accelerator": accelerator_str, - "capture_cuda_graph": str(self.args.capture_cuda_graph) - } - optimization_str = optimization_template.format_map(d) - - config_values = { - "model_name": self.args.triton_model_name, - "platform": self.platform, - "max_batch_size": max_batch_size, - "spec_inputs": spec_inputs, - "spec_outputs": spec_outputs, - "dynamic_batching": batching_str, - "model_optimizations" : optimization_str, - "gpu_list": ", ".join([str(x) for x in range(torch.cuda.device_count())]), - "engine_count": self.args.triton_engine_count - } - - # write config - with open(config_filename, "w") as file: - final_config_str = config_template.format_map(config_values) - final_config_str = remove_empty_lines(final_config_str) - file.write(final_config_str) - - -class Deployer: - def __init__(self, args): - self.args = args - self.lib = DeployerLibrary(args) - - def deploy(self, dataloader, model): - ''' deploy the model and test for correctness with dataloader ''' - if self.args.ts_script or self.args.ts_trace: - self.lib.set_platform("pytorch_libtorch") - print("deploying model " + self.args.triton_model_name + " in format " + self.lib.platform) - self.to_triton_torchscript(dataloader, model) - elif self.args.onnx: - self.lib.set_platform("onnxruntime_onnx") - print("deploying model " + self.args.triton_model_name + " in format " + self.lib.platform) - self.to_triton_onnx(dataloader, model) - elif self.args.trt: - self.lib.set_platform("tensorrt_plan") - print("deploying model " + self.args.triton_model_name + " in format " + self.lib.platform) - self.to_triton_trt(dataloader, model) - else: - assert False, "error" - print("done") - - def to_triton_trt(self, dataloader, model): - ''' export the model to trt and test correctness on dataloader ''' - import tensorrt as trt - # setup device - if self.args.triton_no_cuda: - device = torch.device('cpu') - else: - device = torch.device('cuda') - - assert not self.args.quantize, 'quantize flag not supported by trt' - assert not self.args.calibrate, 'calibrate flag not supported by trt' - - # prepare model - model.to(device) - model.eval() - assert not model.training, "internal error - model should be in eval() mode! " - - # prepare inputs - inputs = self.lib.prepare_inputs(dataloader, device) - - # generate outputs - outputs = [] - for input in inputs: - with torch.no_grad(): - output = model(*input) - if type(output) is torch.Tensor: - output = [output] - outputs.append(output) - - # generate input shapes - dynamic tensor shape support - input_shapes = self.lib.get_tuple_of_dynamic_shapes(inputs) - - # generate output shapes - dynamic tensor shape support - output_shapes = self.lib.get_tuple_of_dynamic_shapes(outputs) - - # generate input types - input_types = [x.dtype for x in inputs[0]] - - # generate output types - output_types = [x.dtype for x in outputs[0]] - - # get input names - rng = range(len(input_types)) - input_names = ["input__" + str(num) for num in rng] - - # get output names - rng = range(len(output_types)) - output_names = ["output__" + str(num) for num in rng] - - # prepare save path - model_folder = os.path.join(self.args.save_dir, self.args.triton_model_name) - version_folder = os.path.join(model_folder, str(self.args.triton_model_version)) - if not os.path.exists(version_folder): - os.makedirs(version_folder) - final_model_path = os.path.join(version_folder, 'model.plan') - - # get indices of dynamic input and output shapes - dynamic_axes = {} - for input_name,shape in zip(input_names,input_shapes): - dynamic_axes[input_name] = [i for i,x in enumerate(shape) if x == -1] - for output_name,shape in zip(output_names,output_shapes): - dynamic_axes[output_name] = [i for i,x in enumerate(shape) if x == -1] - - # export the model to onnx first - with torch.no_grad(): - torch.onnx.export(model, inputs[0], final_model_path, verbose=False, - input_names=input_names, output_names=output_names, - dynamic_axes=dynamic_axes, opset_version=11) - - # get shapes - min_shapes = self.lib.get_tuple_of_min_shapes(inputs) - opt_shapes = self.lib.get_tuple_of_opt_shapes(inputs) - max_shapes = self.lib.get_tuple_of_max_shapes(inputs) - - zipped = zip(input_names, min_shapes, opt_shapes, max_shapes) - shapes = [] - for name,min_shape,opt_shape,max_shape in zipped: - d = { - "name":name, - "min": min_shape, - "opt": opt_shape, - "max": max_shape - } - shapes.append(d) - - # build trt engine - engine = self.lib.build_trt_engine(final_model_path, shapes) - assert engine is not None, " trt export failure " - - # write trt engine - with open(final_model_path, 'wb') as f: - f.write(engine.serialize()) - - # load the model - engine = self.lib.load_engine(final_model_path) - - class TRT_model: - def __init__(self, engine, input_names, output_names, output_types, device): - self.engine = engine - self.context = self.engine.create_execution_context() - self.input_names = input_names - self.output_names = output_names - self.output_types = output_types - self.device = device - - def is_dimension_dynamic(self, dim): - return dim is None or dim <= 0 - - def is_shape_dynamic(self, shape): - return any([self.is_dimension_dynamic(dim) for dim in shape]) - - def __call__(self, *inputs): - # get input shapes - input_shapes = [x.shape for x in inputs] - # bindings - bindings = [None] * self.engine.num_bindings - # set input shapes, bind input tensors - zipped = zip(self.input_names, inputs) - for key,input in zipped: - idx = self.engine.get_binding_index(key) - bindings[idx] = input.data_ptr() - if self.engine.is_shape_binding(idx) and self.is_shape_dynamic(self.context.get_shape(idx)): - self.context.set_shape_input(idx, input) - elif self.is_shape_dynamic(self.engine.get_binding_shape(idx)): - self.context.set_binding_shape(idx, input.shape) - assert self.context.all_binding_shapes_specified, "trt error" - assert self.context.all_shape_inputs_specified, "trt error" - # calculate output shapes, allocate output tensors and bind them - outputs = [] - zipped = zip(self.output_names, self.output_types) - for key,dtype in zipped: - idx = self.engine.get_binding_index(key) - shape = self.context.get_binding_shape(idx) - shape = tuple(shape) - assert -1 not in shape, "trt error" - tensor = torch.zeros(shape, dtype=dtype, device=self.device) - outputs.append(tensor) - bindings[idx] = outputs[-1].data_ptr() - # run inference - self.context.execute_v2(bindings=bindings) - # return the result - if len(outputs) == 1: - outputs = outputs[0] - return outputs - - model_trt = TRT_model(engine, input_names, output_names, output_types, device) - - # run both models on inputs - assert not model.training, "internal error - model should be in eval() mode! " - models = (model, model_trt) - outputs, time_model, outputs_trt, time_model_trt = self.lib.run_models(models, inputs) - - # check for errors - Error_stats = self.lib.compute_errors(outputs, outputs_trt) - self.lib.print_errors(Error_stats) - print('time of error check of native model: ', time_model, 'seconds') - print('time of error check of trt model: ', time_model_trt, 'seconds') - print() - - # write TRTIS config - config_filename = os.path.join(model_folder, "config.pbtxt") - self.lib.write_config(config_filename, - input_shapes, input_types, - output_shapes, output_types) - - def name_onnx_nodes(self, model_path): - ''' - Name all unnamed nodes in ONNX model - parameter model_path: path ONNX model - return: none - ''' - model = onnx.load(model_path) - node_id = 0 - for node in model.graph.node: - if len(node.name) == 0: - node.name = "unnamed_node_%d" % node_id - node_id += 1 - # This check partially validates model - onnx.checker.check_model(model) - onnx.save(model, model_path) - # Only inference really checks ONNX model for some issues - # like duplicated node names - onnxruntime.InferenceSession(model_path, None) - - def to_triton_onnx(self, dataloader, model): - ''' export the model to onnx and test correctness on dataloader ''' - import onnx as local_onnx - global onnx - onnx = local_onnx - import onnxruntime as local_onnxruntime - global onnxruntime - onnxruntime = local_onnxruntime - # setup device - if self.args.triton_no_cuda: - device = torch.device('cpu') - else: - device = torch.device('cuda') - - if self.args.calibrate: - assert self.args.quantize, ("calibrate flag not supported " - "without quantize") - if self.args.quantize: - try: - from quantize import quantize, QuantizationMode - except ImportError as error: - print('quantize scripts are not present') - raise error - - if self.args.calibrate: - try: - import calibrate - except ImportError as error: - print('calibrate scripts are not present') - raise error - - # prepare model - model.to(device) - model.eval() - assert not model.training, "internal error - model should be in eval() mode! " - - # prepare inputs - inputs = self.lib.prepare_inputs(dataloader, device) - - # generate outputs - outputs = [] - for input in inputs: - with torch.no_grad(): - output = model(*input) - if type(output) is torch.Tensor: - output = [output] - outputs.append(output) - - # generate input shapes - dynamic tensor shape support - input_shapes = self.lib.get_tuple_of_dynamic_shapes(inputs) - - # generate output shapes - dynamic tensor shape support - output_shapes = self.lib.get_tuple_of_dynamic_shapes(outputs) - - # generate input types - input_types = [x.dtype for x in inputs[0]] - - # generate output types - output_types = [x.dtype for x in outputs[0]] - - # get input names - rng = range(len(input_types)) - input_names = ["input__" + str(num) for num in rng] - - # get output names - rng = range(len(output_types)) - output_names = ["output__" + str(num) for num in rng] - - # prepare save path - model_folder = os.path.join(self.args.save_dir, self.args.triton_model_name) - version_folder = os.path.join(model_folder, str(self.args.triton_model_version)) - if not os.path.exists(version_folder): - os.makedirs(version_folder) - final_model_path = os.path.join(version_folder, 'model.onnx') - - # get indices of dynamic input and output shapes - dynamic_axes = {} - for input_name,input_shape in zip(input_names,input_shapes): - dynamic_axes[input_name] = [i for i,x in enumerate(input_shape) if x == -1] - for output_name,output_shape in zip(output_names,output_shapes): - dynamic_axes[output_name] = [i for i,x in enumerate(output_shape) if x == -1] - - # export the model - assert not model.training, "internal error - model should be in eval() mode! " - with torch.no_grad(): - torch.onnx.export(model, inputs[0], final_model_path, verbose=False, - input_names=input_names, output_names=output_names, - dynamic_axes=dynamic_axes, opset_version=11) - - # syntactic error check - converted_model = onnx.load(final_model_path) - # check that the IR is well formed - onnx.checker.check_model(converted_model) - - # Name unnamed nodes - it helps for some other processing tools - self.name_onnx_nodes(final_model_path) - converted_model = onnx.load(final_model_path) - - # quantize model - if self.args.quantize: - if not self.args.calibrate: - quantized_model = quantize( - converted_model, - quantization_mode = QuantizationMode.IntegerOps, - ) - # check that the IR is well formed - try: - onnx.checker.check_model(quantized_model) - except onnx.onnx_cpp2py_export.checker.ValidationError as error: - # FIXME: It is unclear, why checker fails for quantized model so - # this error is ignored currently. Inference works for - # some quantized models so lets show warning here - print("model check failed with warning: [", error, "]") - print("Warning during onnx.checker.check_model in quantized model ignored") - onnx.save(quantized_model, final_model_path) - else: - - #assert not self.args.calibrate, 'calibrate flag not supported by ONNX' - # Parsing command-line arguments - #parser = argparse.ArgumentParser(description='parsing model and test data set paths') - #parser.add_argument('--model_path', required=True) - #parser.add_argument('--dataset_path', required=True) - #parser.add_argument('--output_model_path', type=str, default='calibrated_quantized_model.onnx') - #parser.add_argument('--dataset_size', type=int, default=0, help="Number of images or tensors to load. Default is 0 which means all samples") - #parser.add_argument('--data_preprocess', type=str, required=True, choices=['preprocess_method1', 'preprocess_method2', 'None'], help="Refer to Readme.md for guidance on choosing this option.") - #args = parser.parse_args() - #model_path = args.model_path - #output_model_path = args.output_model_path - #images_folder = args.dataset_path - calib_mode = "naive" - size_limit = 0 # int(args.dataset_size) - - # Generating augmented ONNX model - # FIXME: use proper temporary file path - augmented_model_path = 'augmented_model.onnx' - #model = onnx.load(model_path) - augmented_model = calibrate.augment_graph(converted_model) - onnx.checker.check_model(augmented_model) - #onnx.save(augmented_model, final_model_path) - onnx.save(augmented_model, augmented_model_path) - - # Conducting inference - #session = onnxruntime.InferenceSession(final_model_path, None) - print(augmented_model_path) - session = onnxruntime.InferenceSession(augmented_model_path, None) - #session = onnxruntime.InferenceSession('augmented_modelv3.onnx', None) - (samples, channels, height, width) = session.get_inputs()[0].shape - print(session.get_inputs()[0].shape) - #return - - # Generating inputs for quantization - #if args.data_preprocess == "None": - # inputs = load_pb_file(images_folder, args.dataset_size, samples, channels, height, width) - #else: - # inputs = load_batch(images_folder, height, width, args.data_preprocess, size_limit) - - import numpy as np - inputs_calibrate_tmp = inputs[0][0].cpu().numpy() - - dict_for_quantization = calibrate.get_intermediate_outputs( - final_model_path, - session, - inputs_calibrate_tmp, - calib_mode, - ) - quantization_params_dict = calibrate.calculate_quantization_params( - augmented_model, - quantization_thresholds = dict_for_quantization, - ) - calibrated_quantized_model = quantize( - converted_model, - quantization_mode = QuantizationMode.QLinearOps, - quantization_params = quantization_params_dict, - ) - onnx.save(calibrated_quantized_model, final_model_path) - - print("Calibrated, quantized model saved.") - - # load the model - session = onnxruntime.InferenceSession(final_model_path, None) - - class ONNX_model: - def __init__(self, session, input_names, device): - self.session = session - self.input_names = input_names - - def to_numpy(self, tensor): - return tensor.detach().cpu().numpy() if tensor.requires_grad else tensor.cpu().numpy() - - def __call__(self, *inputs): - inp = [(input_name, inputs[i]) for i,input_name in enumerate(self.input_names)] - inp = {input_name : self.to_numpy(x) for input_name,x in inp} - outputs = self.session.run(None, inp) - outputs = [torch.from_numpy(output) for output in outputs] - outputs = [output.to(device) for output in outputs] - if len(outputs) == 1: - outputs = outputs[0] - return outputs - - # switch to eval mode - model_onnx = ONNX_model(session, input_names, device) - - # run both models on inputs - assert not model.training, "internal error - model should be in eval() mode! " - models = (model, model_onnx) - outputs, time_model, outputs_onnx, time_model_onnx = self.lib.run_models(models, inputs) - - # check for errors - Error_stats = self.lib.compute_errors(outputs, outputs_onnx) - self.lib.print_errors(Error_stats) - print('time of error check of native model: ', time_model, 'seconds') - print('time of error check of onnx model: ', time_model_onnx, 'seconds') - print() - - # write TRTIS config - config_filename = os.path.join(model_folder, "config.pbtxt") - self.lib.write_config(config_filename, - input_shapes, input_types, - output_shapes, output_types) - - def to_triton_torchscript(self, dataloader, model): - ''' export the model to torchscript and test correctness on dataloader ''' - # setup device - if self.args.triton_no_cuda: - device = torch.device('cpu') - else: - device = torch.device('cuda') - - # prepare model - model.to(device) - model.eval() - assert not model.training, "internal error - model should be in eval() mode! " - - #TODO: support quantize - assert not self.args.quantize, 'quantize flag not supported by torchscript yet' - - # prepare inputs - inputs = self.lib.prepare_inputs(dataloader, device) - - # generate input shapes - dynamic tensor shape support - input_shapes = self.lib.get_tuple_of_dynamic_shapes(inputs) - - # generate input types - input_types = [x.dtype for x in inputs[0]] - - # prepare save path - model_folder = os.path.join(self.args.save_dir, self.args.triton_model_name) - version_folder = os.path.join(model_folder, str(self.args.triton_model_version)) - if not os.path.exists(version_folder): - os.makedirs(version_folder) - final_model_path = os.path.join(version_folder, 'model.pt') - - # convert the model - with torch.no_grad(): - if self.args.ts_trace: # trace it - model_ts = torch.jit.trace(model, inputs[0]) - if self.args.ts_script: # script it - model_ts = torch.jit.script(model) - - # save the model - torch.jit.save(model_ts, final_model_path) - - # load the model - model_ts = torch.jit.load(final_model_path) - model_ts.eval() # WAR for bug : by default, model_ts gets loaded in training mode - - # run both models on inputs - assert not model.training, "internal error - model should be in eval() mode! " - assert not model_ts.training, "internal error - converted model should be in eval() mode! " - models = (model, model_ts) - outputs, time_model, outputs_ts, time_model_ts = self.lib.run_models(models, inputs) - - # check for errors - Error_stats = self.lib.compute_errors(outputs, outputs_ts) - self.lib.print_errors(Error_stats) - print('time of error check of native model: ', time_model, 'seconds') - print('time of error check of ts model: ', time_model_ts, 'seconds') - print() - - # generate output shapes - dynamic tensor shape support - output_shapes = self.lib.get_tuple_of_dynamic_shapes(outputs) - - # generate output types - output_types = [x.dtype for x in outputs[0]] - - # now we build the config for TRTIS - config_filename = os.path.join(model_folder, "config.pbtxt") - self.lib.write_config(config_filename, - input_shapes, input_types, - output_shapes, output_types) - - diff --git a/PyTorch/NLP/Transformer/scripts/docker/build.sh b/PyTorch/NLP/Transformer/scripts/docker/build.sh deleted file mode 100644 index 6dca1e2e..00000000 --- a/PyTorch/NLP/Transformer/scripts/docker/build.sh +++ /dev/null @@ -1 +0,0 @@ -docker build . --network=host -t transformer_pyt diff --git a/PyTorch/NLP/Transformer/scripts/docker/launch.sh b/PyTorch/NLP/Transformer/scripts/docker/launch.sh deleted file mode 100644 index 0c39f2b0..00000000 --- a/PyTorch/NLP/Transformer/scripts/docker/launch.sh +++ /dev/null @@ -1,15 +0,0 @@ -#!/bin/bash - -CMD=${1:-/bin/bash} -NV_VISIBLE_DEVICES=${2:-"0,1,2,3,4,5,6,7,8"} -DOCKER_BRIDGE=${3:-"host"} - -nvidia-docker run -it --rm \ - --net=$DOCKER_BRIDGE \ - --shm-size=1g \ - --ulimit memlock=-1 \ - --ulimit stack=67108864 \ - -e NVIDIA_VISIBLE_DEVICES=${NV_VISIBLE_DEVICES} \ - -v $PWD/results:/results \ - -v $PWD/data:/data \ - transformer_pyt $CMD diff --git a/PyTorch/NLP/Transformer/scripts/draw_summary.py b/PyTorch/NLP/Transformer/scripts/draw_summary.py deleted file mode 100644 index 02e1dbb2..00000000 --- a/PyTorch/NLP/Transformer/scripts/draw_summary.py +++ /dev/null @@ -1,134 +0,0 @@ -import json -import argparse -from collections import defaultdict, OrderedDict -import matplotlib.pyplot as plt -import numpy as np - -def smooth_moving_average(x, n): - fil = np.ones(n)/n - smoothed = np.convolve(x, fil, mode='valid') - smoothed = np.concatenate((x[:n-1], smoothed), axis=0) - - return smoothed - -def moving_stdev(x, n): - fil = np.ones(n)/n - avg_sqare = np.convolve(np.power(x, 2), fil, mode='valid') - squared_avg = np.power(np.convolve(x, fil, mode='valid'), 2) - var = avg_sqare - squared_avg - stdev = np.sqrt(var) - #pad first few values - stdev = np.concatenate(([0]*(n-1), stdev), axis=0) - - return stdev - -def get_plot(log): - steps = [x[0] for x in log if isinstance(x[0], int)] - values = [x[2] for x in log if isinstance(x[0], int)] - return steps, values - -def highlight_max_point(plot, color): - point = max(zip(*plot), key=lambda x: x[1]) - plt.plot(point[0], point[1], 'bo-', color=color) - plt.annotate("{:.2f}".format(point[1]), point) - return point - -def main(args): - jlog = defaultdict(list) - jlog['parameters'] = {} - - with open(args.log_file, 'r') as f: - for line in f.readlines(): - line_dict = json.loads(line[5:]) - if line_dict['type'] == 'LOG': - if line_dict['step'] == 'PARAMETER': - jlog['parameters'].update(line_dict['data']) - elif line_dict['step'] == [] and 'training_summary' not in jlog: - jlog['training_summary']=line_dict['data'] - else: - for k, v in line_dict['data'].items(): - jlog[k].append((line_dict['step'], line_dict['elapsedtime'], v)) - - fig, ax1 = plt.subplots(figsize=(20,5)) - fig.suptitle(args.title, fontsize=16) - ax1.set_xlabel('steps') - ax1.set_ylabel('loss') - - # Define colors for specific curves - VAL_LOSS_COLOR = 'blue' - VAL_BLEU_COLOR = 'red' - TEST_BLEU_COLOR = 'pink' - - # Plot smoothed loss curve - steps, loss = get_plot(jlog['loss']) - smoothed_loss = smooth_moving_average(loss, 150) - stdev = moving_stdev(loss, 150) - - ax1.plot(steps, smoothed_loss, label='Training loss') - ax1.plot(steps, smoothed_loss + stdev, '--', color='orange', linewidth=0.3, label='Stdev') - ax1.plot(steps, smoothed_loss - stdev, '--', color='orange', linewidth=0.3) - - # Plot validation loss curve - val_steps, val_loss = get_plot(jlog['val_loss']) - ax1.plot(val_steps, val_loss, color='blue', label='Validation loss') - - min_val_loss_step = val_steps[np.argmin(val_loss)] - ax1.axvline(min_val_loss_step, linestyle='dashed', color=VAL_LOSS_COLOR, linewidth=0.5, label='Validation loss minimum') - - # Plot BLEU curves - ax2 = ax1.twinx() - ax2.set_ylabel('BLEU') - val_steps, val_bleu = get_plot(jlog['val_bleu']) - ax2.plot(val_steps, val_bleu, color=VAL_BLEU_COLOR, label='Validation BLEU') - mvb_step, _ =highlight_max_point((val_steps,val_bleu), color=VAL_BLEU_COLOR) - - # values to be labeled on plot - max_val_bleu_step = val_steps[np.argmax(val_bleu)] - max_val_bleu = val_bleu[val_steps.index(max_val_bleu_step)] - min_loss_bleu = val_bleu[val_steps.index(min_val_loss_step)] - - - if 'test_bleu' in jlog: - test_steps, test_bleu = get_plot(jlog['test_bleu']) - ax2.plot(val_steps, test_bleu, color=TEST_BLEU_COLOR, label='Test BLEU') - highlight_max_point((test_steps, test_bleu), color=TEST_BLEU_COLOR) - ax2.tick_params(axis='y') - - # Annotate points with highest BLEU score as well as those for minimal validation loss - ax2.plot(min_val_loss_step, min_loss_bleu, 'bo-', color=VAL_BLEU_COLOR) - ax2.annotate("{:.2f}".format(min_loss_bleu), (min_val_loss_step, min_loss_bleu)) - - if 'test_bleu' in jlog: - min_loss_test_bleu = test_bleu[val_steps.index(min_val_loss_step)] #BLEU score on test set when validation loss is minimal - ax2.plot(min_val_loss_step, min_loss_test_bleu, 'bo-', color=TEST_BLEU_COLOR) - ax2.annotate("{:.2f}".format(min_loss_test_bleu), (min_val_loss_step, min_loss_test_bleu)) - - max_val_bleu_test = test_bleu[val_steps.index(max_val_bleu_step)] #BLEU score on test set when BLEU score on dev set is maximal - ax2.plot(mvb_step, max_val_bleu_test, 'bo-', color=TEST_BLEU_COLOR) - ax2.annotate("{:.2f}".format(max_val_bleu_test), (max_val_bleu_step, max_val_bleu_test)) - - ax1.legend(loc='lower left', bbox_to_anchor=(1,0)) - ax2.legend(loc='upper left', bbox_to_anchor=(1,1)) - plt.grid() - plt.savefig(args.output) - - # Produce json with training summary - if args.dump_json: - summary = OrderedDict() - summary['args'] = OrderedDict(jlog['parameters']) - summary['min_val_loss'] = min(val_loss) - summary['max_val_bleu'] = max(val_bleu) - summary['max_test_bleu'] = max(test_bleu) - summary['final_values'] = jlog['training_summary'] - summary['avg_epoch_loss'] = [x.mean() for x in np.array_split(np.array(loss), jlog['parameters']['max_epoch'])] - summary['min_val_loss_step'] = min_val_loss_step - json.dump(summary, open(args.dump_json, 'w')) - -if __name__=='__main__': - parser = argparse.ArgumentParser() - parser.add_argument('--title', type=str) - parser.add_argument('--log-file', type=str) - parser.add_argument('--output' ,'-o', type=str) - parser.add_argument('--dump-json', '-j', type=str) - args = parser.parse_args() - main(args) diff --git a/PyTorch/NLP/Transformer/scripts/export_model.sh b/PyTorch/NLP/Transformer/scripts/export_model.sh deleted file mode 100644 index 85880c97..00000000 --- a/PyTorch/NLP/Transformer/scripts/export_model.sh +++ /dev/null @@ -1,54 +0,0 @@ -#!/bin/bash - -# Copyright (c) 2020 NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -NV_VISIBLE_DEVICES=${1:-"0"} -DOCKER_BRIDGE=${2:-"host"} -checkpoint=${3:-"/checkpoints/checkpoint_jit.pt"} -batch_size=${4:-"5120"} -WORKSPACE=${5:-"/workspace/translation"} -triton_model_version=${6:-1} -triton_model_name=${7:-"transformer"} -triton_dyn_batching_delay=${8:-0} -triton_engine_count=${9:-1} -triton_model_overwrite=${10:-"False"} - -DEPLOYER="deployer.py" - -#TODO: add fp16 option - -CMD="python triton/${DEPLOYER} \ - --ts-script \ - --save-dir ${WORKSPACE}/triton/triton_models \ - --triton-model-name ${triton_model_name} \ - --triton-model-version ${triton_model_version} \ - --triton-max-batch-size ${batch_size} \ - --triton-dyn-batching-delay ${triton_dyn_batching_delay} \ - --triton-engine-count ${triton_engine_count} " - -ENCODER_EXPORT_CMD="$CMD --triton-model-name ${triton_model_name}-encoder" -DECODER_EXPORT_CMD="$CMD --triton-model-name ${triton_model_name}-decoder" - -MODEL_ARGS=" -- --checkpoint ${checkpoint} \ - --batch-size=${batch_size} \ - --num-batches=2 \ - --data /data " - -ENCODER_EXPORT_CMD+="${MODEL_ARGS} --part encoder" -DECODER_EXPORT_CMD+="${MODEL_ARGS} --part decoder" - -echo Exporting encoder... -bash scripts/docker/launch.sh "${ENCODER_EXPORT_CMD}" ${NV_VISIBLE_DEVICES} ${DOCKER_BRIDGE} -echo Exporting decoder... -bash scripts/docker/launch.sh "${DECODER_EXPORT_CMD}" ${NV_VISIBLE_DEVICES} ${DOCKER_BRIDGE} diff --git a/PyTorch/NLP/Transformer/scripts/run_DGX1_AMP_8GPU.sh b/PyTorch/NLP/Transformer/scripts/run_DGX1_AMP_8GPU.sh deleted file mode 100644 index b69e52d7..00000000 --- a/PyTorch/NLP/Transformer/scripts/run_DGX1_AMP_8GPU.sh +++ /dev/null @@ -1,57 +0,0 @@ -#! /bin/bash -# -# Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -nvidia-smi - -RESULTS_DIR='/results' -CHECKPOINTS_DIR='/results/checkpoints' -STAT_FILE=${RESULTS_DIR}/DGX1_amp_8GPU.json -mkdir -p $CHECKPOINTS_DIR - -SEED=${1:-1} -LR=${2:-0.000846} -WARMUP=${3:-4000} -NUM_EPOCHS=${4:-40} -BATCH_SIZE=${5:-10240} -NUM_GPU=${6:-8} - -DISTRIBUTED="-m torch.distributed.launch --nproc_per_node=${NUM_GPU}" - -python ${DISTRIBUTED} /workspace/translation/train.py \ - /data/wmt14_en_de_joined_dict \ - --arch transformer_wmt_en_de_big_t2t \ - --share-all-embeddings \ - --optimizer adam \ - --adam-betas 0.9 0.997 \ - --adam-eps 1e-9 \ - --clip-norm 0.0 \ - --lr-scheduler inverse_sqrt \ - --warmup-init-lr 0.0 \ - --warmup-updates ${WARMUP} \ - --lr $LR \ - --min-lr 0.0 \ --dropout 0.1 \ - --weight-decay 0.0 \ - --criterion label_smoothed_cross_entropy \ - --label-smoothing 0.1 \ - --max-tokens ${BATCH_SIZE} \ - --seed ${SEED} \ - --max-epoch ${NUM_EPOCHS} \ - --no-epoch-checkpoints \ - --fuse-layer-norm \ - --online-eval \ - --log-interval 500 \ - --save-dir ${RESULTS_DIR} \ - --stat-file ${STAT_FILE} \ - --amp diff --git a/PyTorch/NLP/Transformer/scripts/run_DGX1_FP32_8GPU.sh b/PyTorch/NLP/Transformer/scripts/run_DGX1_FP32_8GPU.sh deleted file mode 100644 index 2f18426d..00000000 --- a/PyTorch/NLP/Transformer/scripts/run_DGX1_FP32_8GPU.sh +++ /dev/null @@ -1,57 +0,0 @@ -#! /bin/bash -# -# Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -nvidia-smi - -RESULTS_DIR='/results' -CHECKPOINTS_DIR='/results/checkpoints' -STAT_FILE=${RESULTS_DIR}/DGX1_fp32_8GPU.json -mkdir -p $CHECKPOINTS_DIR - -SEED=${1:-1} -LR=${2:-0.0006} -WARMUP=${3:-4000} -NUM_EPOCHS=${4:-40} -BATCH_SIZE=${5:-5120} -NUM_GPU=${6:-8} - -DISTRIBUTED="-m torch.distributed.launch --nproc_per_node=${NUM_GPU}" - -python ${DISTRIBUTED} /workspace/translation/train.py \ - /data/wmt14_en_de_joined_dict \ - --arch transformer_wmt_en_de_big_t2t \ - --share-all-embeddings \ - --optimizer adam \ - --adam-betas 0.9 0.997 \ - --adam-eps 1e-9 \ - --clip-norm 0.0 \ - --lr-scheduler inverse_sqrt \ - --warmup-init-lr 0.0 \ - --warmup-updates ${WARMUP} \ - --lr $LR \ - --min-lr 0.0 \ - --dropout 0.1 \ - --weight-decay 0.0 \ - --criterion label_smoothed_cross_entropy \ - --label-smoothing 0.1 \ - --max-tokens ${BATCH_SIZE} \ - --seed ${SEED} \ - --max-epoch ${NUM_EPOCHS} \ - --no-epoch-checkpoints \ - --fuse-layer-norm \ - --online-eval \ - --log-interval 500 \ - --save-dir ${RESULTS_DIR} \ - --stat-file ${STAT_FILE} diff --git a/PyTorch/NLP/Transformer/scripts/run_DGXA100_AMP_8GPU.sh b/PyTorch/NLP/Transformer/scripts/run_DGXA100_AMP_8GPU.sh deleted file mode 100644 index c7d9854d..00000000 --- a/PyTorch/NLP/Transformer/scripts/run_DGXA100_AMP_8GPU.sh +++ /dev/null @@ -1,58 +0,0 @@ -#! /bin/bash -# -# Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -nvidia-smi - -RESULTS_DIR='/results' -CHECKPOINTS_DIR='/results/checkpoints' -STAT_FILE=${RESULTS_DIR}/DGXA100_amp_8GPU_log.json -mkdir -p $CHECKPOINTS_DIR - -SEED=${1:-1} -LR=${2:-0.000846} -WARMUP=${3:-4000} -NUM_EPOCHS=${4:-40} -BATCH_SIZE=${5:-10240} -NUM_GPU=${6:-8} - -DISTRIBUTED="-m torch.distributed.launch --nproc_per_node=${NUM_GPU}" - -python ${DISTRIBUTED} /workspace/translation/train.py \ - /data/wmt14_en_de_joined_dict \ - --arch transformer_wmt_en_de_big_t2t \ - --share-all-embeddings \ - --optimizer adam \ - --adam-betas 0.9 0.997 \ - --adam-eps 1e-9 \ - --clip-norm 0.0 \ - --lr-scheduler inverse_sqrt \ - --warmup-init-lr 0.0 \ - --warmup-updates ${WARMUP} \ - --lr $LR \ - --min-lr 0.0 \ - --dropout 0.1 \ - --weight-decay 0.0 \ - --criterion label_smoothed_cross_entropy \ - --label-smoothing 0.1 \ - --max-tokens ${BATCH_SIZE} \ - --seed ${SEED} \ - --max-epoch ${NUM_EPOCHS} \ - --no-epoch-checkpoints \ - --fuse-layer-norm \ - --online-eval \ - --log-interval 500 \ - --save-dir ${RESULTS_DIR} \ - --stat-file ${STAT_FILE} \ - --amp diff --git a/PyTorch/NLP/Transformer/scripts/run_DGXA100_TF32_8GPU.sh b/PyTorch/NLP/Transformer/scripts/run_DGXA100_TF32_8GPU.sh deleted file mode 100644 index 418544f6..00000000 --- a/PyTorch/NLP/Transformer/scripts/run_DGXA100_TF32_8GPU.sh +++ /dev/null @@ -1,66 +0,0 @@ -#! /bin/bash -# -# Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -nvidia-smi - -RESULTS_DIR='/results' -CHECKPOINTS_DIR='/results/checkpoints' -STAT_FILE=${RESULTS_DIR}/DGXA100_tf32_8GPU_log.json -mkdir -p $CHECKPOINTS_DIR - -PREC=${1:-'tf32'} -SEED=${2:-1} -LR=${3:-0.000846} -WARMUP=${4:-4000} -NUM_EPOCHS=${5:-40} -BATCH_SIZE=${6:-10240} -NUM_GPU=${7:-8} - -DISTRIBUTED="-m torch.distributed.launch --nproc_per_node=${NUM_GPU}" - -if [ "$PREC" = "fp32" ]; -then - PREC='' - export NVIDIA_TF32_OVERRIDE=0 -else - PREC='' -fi - -python ${DISTRIBUTED} /workspace/translation/train.py \ - /data/wmt14_en_de_joined_dict \ - --arch transformer_wmt_en_de_big_t2t \ - --share-all-embeddings \ - --optimizer adam \ - --adam-betas 0.9 0.997 \ - --adam-eps 1e-9 \ - --clip-norm 0.0 \ - --lr-scheduler inverse_sqrt \ - --warmup-init-lr 0.0 \ - --warmup-updates ${WARMUP} \ - --lr $LR \ - --min-lr 0.0 \ - --dropout 0.1 \ - --weight-decay 0.0 \ - --criterion label_smoothed_cross_entropy \ - --label-smoothing 0.1 \ - --max-tokens ${BATCH_SIZE} \ - --seed ${SEED} \ - --max-epoch ${NUM_EPOCHS} \ - --no-epoch-checkpoints \ - --fuse-layer-norm \ - --online-eval \ - --log-interval 500 \ - --save-dir ${RESULTS_DIR} \ - --stat-file ${STAT_FILE} diff --git a/PyTorch/NLP/Transformer/scripts/run_preprocessing.sh b/PyTorch/NLP/Transformer/scripts/run_preprocessing.sh deleted file mode 100644 index 8def2ed4..00000000 --- a/PyTorch/NLP/Transformer/scripts/run_preprocessing.sh +++ /dev/null @@ -1,35 +0,0 @@ -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -DATASET_DIR=/data/wmt14_en_de_joined_dict -TEXT=examples/translation/wmt14_en_de - -( - cd examples/translation - bash prepare-wmt14en2de.sh --scaling18 -) - -python preprocess.py \ - --source-lang en \ - --target-lang de \ - --trainpref $TEXT/train \ - --validpref $TEXT/valid \ - --testpref $TEXT/test \ - --destdir ${DATASET_DIR} \ - --nwordssrc 33712 \ - --nwordstgt 33712 \ - --joined-dictionary - -cp $TEXT/code $DATASET_DIR/code -cp $TEXT/tmp/valid.raw.de $DATASET_DIR/valid.raw.de -sacrebleu -t wmt14/full -l en-de --echo ref > $DATASET_DIR/test.raw.de diff --git a/PyTorch/NLP/Transformer/scripts/run_training.sh b/PyTorch/NLP/Transformer/scripts/run_training.sh deleted file mode 100644 index d9d6b401..00000000 --- a/PyTorch/NLP/Transformer/scripts/run_training.sh +++ /dev/null @@ -1,71 +0,0 @@ -#! /bin/bash -# -# Copyright (c) 2020, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -nvidia-smi - -RESULTS_DIR='/results' -CHECKPOINTS_DIR='/results/checkpoints' -STAT_FILE=${RESULTS_DIR}/run_log.json -mkdir -p $CHECKPOINTS_DIR - -: ${PREC:='amp'} -: ${SEED:=1} -: ${LR:=0.000846} -: ${WARMUP:=4000} -: ${NUM_EPOCHS:=40} -: ${BS:=5120} -: ${NUM_GPU:=8} -: ${USE_SLURM:=0} -: ${USE_DISTRIBUTED:=1} - -DISTRIBUTED="" -[ ${USE_DISTRIBUTED} = 1 ] && DISTRIBUTED+="-m torch.distributed.launch --nproc_per_node=${NUM_GPU}" -[ ${USE_DISTRIBUTED} = 1 ] && [ ${USE_SLURM} = 1 ] && DISTRIBUTED+=" --nnodes ${WORLD_SIZE} --node_rank ${SLURM_NODEID} \ - --master_addr ${MASTER_ADDR} --master_port ${MASTER_PORT} " - -if [ "$PREC" = "amp" ]; -then - PREC='--amp ' -else - PREC='' -fi - -python ${DISTRIBUTED} /workspace/translation/train.py \ - /data/ \ - --arch transformer_wmt_en_de_big_t2t \ - --share-all-embeddings \ - --optimizer adam \ - --adam-betas 0.9 0.997 \ - --adam-eps 1e-9 \ - --clip-norm 0.0 \ - --lr-scheduler inverse_sqrt \ - --warmup-init-lr 0.0 \ - --warmup-updates ${WARMUP} \ - --lr $LR \ - --min-lr 0.0 \ - --dropout 0.1 \ - --weight-decay 0.0 \ - --criterion label_smoothed_cross_entropy \ - --label-smoothing 0.1 \ - --max-tokens ${BS} \ - --seed ${SEED} \ - --max-epoch ${NUM_EPOCHS} \ - --no-save \ - --fuse-layer-norm \ - --online-eval \ - --log-interval 500 \ - --save-dir ${RESULTS_DIR} \ - --stat-file ${STAT_FILE} \ - ${PREC} diff --git a/PyTorch/NLP/Transformer/setup.py b/PyTorch/NLP/Transformer/setup.py deleted file mode 100644 index 6cd066f5..00000000 --- a/PyTorch/NLP/Transformer/setup.py +++ /dev/null @@ -1,79 +0,0 @@ -#!/usr/bin/env python3 -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from setuptools import setup, find_packages, Extension -from torch.utils.cpp_extension import BuildExtension, CUDAExtension, CppExtension -import sys - - -if sys.version_info < (3,): - sys.exit('Sorry, Python3 is required for fairseq.') - -with open('README.md') as f: - readme = f.read() - -with open('LICENSE') as f: - license = f.read() - -with open('requirements.txt') as f: - reqs = f.read() - - -extra_compile_args = {'cxx' : ['-O2']} -extra_compile_args['nvcc'] = ['-O3', - '-I./cutlass/', - '-U__CUDA_NO_HALF_OPERATORS__', - '-U__CUDA_NO_HALF_CONVERSIONS__', - '-gencode', 'arch=compute_70,code=sm_70', - '-gencode', 'arch=compute_70,code=compute_70', - '-gencode', 'arch=compute_80,code=sm_80', - '-gencode', 'arch=compute_80,code=compute_80', - ] - -strided_batched_gemm = CUDAExtension( - name='strided_batched_gemm', - sources=['fairseq/modules/strided_batched_gemm/strided_batched_gemm.cpp', 'fairseq/modules/strided_batched_gemm/strided_batched_gemm_cuda.cu'], - extra_compile_args=extra_compile_args -) - -batch_utils = CppExtension( - name='fairseq.data.batch_C', - sources=['fairseq/data/csrc/make_batches.cpp'], - extra_compile_args={ - 'cxx': ['-O2',], - } -) -setup( - name='fairseq', - version='0.5.0', - description='Facebook AI Research Sequence-to-Sequence Toolkit', - long_description=readme, - license=license, - install_requires=reqs.strip().split('\n'), - packages=find_packages(), - ext_modules=[strided_batched_gemm, batch_utils], - cmdclass={ - 'build_ext': BuildExtension.with_options(use_ninja=False) - }, - test_suite='tests', -) diff --git a/PyTorch/NLP/Transformer/train.py b/PyTorch/NLP/Transformer/train.py deleted file mode 100644 index a749e535..00000000 --- a/PyTorch/NLP/Transformer/train.py +++ /dev/null @@ -1,430 +0,0 @@ -#!/usr/bin/env python3 -u -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. -# -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# -#------------------------------------------------------------------------- -# -# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -import collections -import os -import math -import time -import ctypes - -from copy import deepcopy - -import torch -import sacrebleu -import dllogger as DLLogger - -from fairseq import data, distributed_utils, options, utils, tokenizer -from fairseq.ddp_trainer import DDPTrainer -from fairseq.meters import StopwatchMeter -from fairseq.sequence_generator import SequenceGenerator -from fairseq.data import data_utils, load_dataset_splits -from fairseq.models import build_model -from fairseq.log_helper import setup_logger, reset_perf_meters - -def main(args): - - print(args) - setup_logger(args) - - if not torch.cuda.is_available(): - raise NotImplementedError('Training on CPU is not supported') - torch.cuda.set_device(args.device_id) - if args.distributed_world_size > 1: - assert torch.distributed.is_initialized() - torch.distributed.broadcast(torch.tensor([1], device="cuda"), 0) - torch.cuda.synchronize() - pValue = ctypes.cast((ctypes.c_int * 1)(), ctypes.POINTER(ctypes.c_int)) - ctypes.CDLL('libcudart.so').cudaDeviceSetLimit(ctypes.c_int(0x05), ctypes.c_int(128)) - ctypes.CDLL('libcudart.so').cudaDeviceGetLimit(pValue, ctypes.c_int(0x05)) - torch.manual_seed(args.seed) - - src_dict, tgt_dict = data_utils.load_dictionaries(args) - add_extra_items_to_checkpoint({'src_dict': src_dict, 'tgt_dict': tgt_dict}) - datasets = load_dataset_splits(args, ['train', 'valid', 'test'], src_dict, tgt_dict) - - model = build_model(args) - print('| num. model params: {}'.format(sum(p.numel() for p in model.parameters()))) - - # Build trainer - if torch.cuda.get_device_capability(0)[0] >= 7 and not args.amp: - print('| NOTICE: your device may support faster training with --amp') - trainer = DDPTrainer(args, model) - print('| model {}, criterion {}'.format(args.arch, trainer.criterion.__class__.__name__)) - print('| training on {} GPUs'.format(args.distributed_world_size)) - print('| max tokens per GPU = {} and max sentences per GPU = {}'.format( - args.max_tokens, - args.max_sentences, - )) - - epoch_itr = data.EpochBatchIterator( - dataset=datasets[args.train_subset], - max_tokens=args.max_tokens, - max_sentences=args.max_sentences_valid, - max_positions=args.max_positions, - required_batch_size_multiple=8, - seed=args.seed, - num_shards=args.distributed_world_size, - shard_id=args.distributed_rank, - ) - # Load the latest checkpoint if one is available - load_checkpoint(args, trainer, epoch_itr) - - # Send a dummy batch to warm the caching allocator - dummy_batch = data_utils.get_dummy_batch(args.max_tokens, src_dict, tgt_dict) - trainer.dummy_train_step(dummy_batch) - - # Sanity check - if args.do_sanity_check: - print('Performing sanity check...') - sanity_score = score(args, trainer, datasets['test'], src_dict, tgt_dict, 'test.raw.de') - DLLogger.log(step='SANITY_CHECK', data={'sanity_check_score': sanity_score}, verbosity=1) - - # Train until the learning rate gets too small or model reaches target score - max_epoch = args.max_epoch or math.inf - max_update = args.max_update or math.inf - tgt_bleu = args.target_bleu or math.inf - current_bleu = 0.0 - best_bleu = -1.0 - lr = trainer.get_lr() - train_meter = StopwatchMeter() - train_meter.start() - valid_losses = [None] - valid_subsets = args.valid_subset.split(',') - run_summary = {'loss': float('inf'), - 'val_loss': float('inf'), - 'speed': 0, - 'accuracy': 0} - - while lr >= args.min_lr and epoch_itr.epoch < max_epoch and trainer.get_num_updates() < max_update and current_bleu < tgt_bleu: - DLLogger.log(step=trainer.get_num_updates()+1, data={'epoch': epoch_itr.epoch}, verbosity=0) - # train for one epoch - train(args, trainer, epoch_itr) - DLLogger.log(step=trainer.get_num_updates(), data={'walltime': train_meter.sum}, verbosity=1) - DLLogger.log(step=trainer.get_num_updates(), - data={'avg_epoch_loss': trainer.avg_loss_meter.avg}, verbosity=1) - - if epoch_itr.epoch % args.validate_interval == 0: - valid_losses = validate(args, trainer, datasets, valid_subsets) - valid_bleu = score(args, trainer, datasets[valid_subsets[0]], src_dict, tgt_dict, 'valid.raw.de') - DLLogger.log(step=trainer.get_num_updates(), - data={'val_loss': valid_losses[0], 'val_bleu': valid_bleu}, verbosity=1) - - # Eval BLEU score - if args.online_eval or (tgt_bleu is not math.inf): - current_bleu = score(args, trainer, datasets[args.gen_subset], src_dict, tgt_dict, 'test.raw.de') - DLLogger.log(step=trainer.get_num_updates(), data={'test_bleu': current_bleu}, verbosity=1) - best_bleu = max(best_bleu, current_bleu) - - run_summary['val_loss'] = min(run_summary['val_loss'], valid_losses[0]) - run_summary['accuracy'] = best_bleu if best_bleu >= 0 else valid_bleu - run_summary['loss'] = valid_losses[0] - run_summary['speed'] = trainer.throughput_meter.u_avg - - # Only use first validation loss to update the learning rate - lr = trainer.lr_step(epoch_itr.epoch, valid_losses[0]) - - save_checkpoint(args, trainer, epoch_itr, valid_losses[0]) - - train_meter.stop() - run_summary['walltime'] = train_meter.sum - DLLogger.log(step=(), data=run_summary, verbosity=0) - print('| done training in {:.1f} seconds'.format(train_meter.sum)) - -def train(args, trainer, epoch_itr): - """Train the model for one epoch.""" - - # Initialize data iterator - itr = epoch_itr.next_epoch_itr() - - # update parameters every N batches - if epoch_itr.epoch <= len(args.update_freq): - update_freq = args.update_freq[epoch_itr.epoch - 1] - else: - update_freq = args.update_freq[-1] - - max_update = args.max_update or math.inf - num_batches = len(epoch_itr) - begin = time.time() - - # reset meters - DLLogger.flush() - trainer.get_throughput_meter().reset() - - for i, sample in enumerate(itr): - if i < num_batches - 1 and (i + 1) % update_freq > 0: - # buffer updates according to --update-freq - trainer.train_step(sample, update_params=False, last_step=(i == len(itr)-1)) - continue - else: - trainer.train_step(sample, update_params=True, last_step=(i == len(itr)-1)) - - # ignore the first mini-batch in words-per-second calculation - if i == 0: - trainer.get_throughput_meter().reset() - reset_perf_meters() - - if (i+1) % args.log_interval == 0: - DLLogger.flush() - - if trainer.get_num_updates() >= max_update: - break - - print('Epoch time:', time.time() - begin) - - # Print epoch stats and reset training meters - DLLogger.log(step=trainer.get_num_updates(), - data={'speed': trainer.get_throughput_meter().avg}, verbosity=0) - DLLogger.flush() - -def validate(args, trainer, datasets, subsets): - """Evaluate the model on the validation set(s) and return the losses.""" - - valid_losses = [] - for subset in subsets: - - if len(subsets) > 1: - print('Validating on \'{}\' subset'.format(subset)) - - # Initialize data iterator - itr = data.EpochBatchIterator( - dataset=datasets[subset], - max_tokens=args.max_tokens, - max_sentences=args.max_sentences_valid, - max_positions=args.max_positions, - required_batch_size_multiple=8, - seed=args.seed, - num_shards=args.distributed_world_size, - shard_id=args.distributed_rank, - ).next_epoch_itr(shuffle=False) - - # reset validation loss meters - DLLogger.flush() - - subset_losses = [] - for sample in itr: - loss = trainer.valid_step(sample) - subset_losses.append(loss) - subset_loss = sum(subset_losses)/len(subset_losses) - - DLLogger.flush() - - valid_losses.append(subset_loss) - print(f'Validation loss on subset {subset}: {subset_loss}') - - return valid_losses - -def score(args, trainer, dataset, src_dict, tgt_dict, ref_file): - - begin = time.time() - - src_dict = deepcopy(src_dict) # This is necessary, generation of translations - tgt_dict = deepcopy(tgt_dict) # alters target dictionary messing up with the rest of training - - model = trainer.get_model() - - # Initialize data iterator - itr = data.EpochBatchIterator( - dataset=dataset, - max_tokens=None, - max_sentences=max(8, min(math.ceil(1024/args.distributed_world_size), 128)), - max_positions=args.max_positions, - required_batch_size_multiple=8, - num_shards=args.distributed_world_size, - shard_id=args.distributed_rank, - ).next_epoch_itr(shuffle=False) - - # Initialize generator - gen_timer = StopwatchMeter() - translator = SequenceGenerator( - [model], - tgt_dict.get_metadata(), - maxlen=args.max_target_positions - 1, # do not include EOS token - beam_size=args.beam, - stop_early=(not args.no_early_stop), normalize_scores=(not args.unnormalized), - len_penalty=args.lenpen, unk_penalty=args.unkpen, - sampling=args.sampling, sampling_topk=args.sampling_topk, minlen=args.min_len, - use_amp=args.amp, - ) - # Generate and compute BLEU - predictions = [] - translations = translator.generate_batched_itr( - itr, maxlen_a=args.max_len_a, maxlen_b=args.max_len_b, - cuda=True, timer=gen_timer, prefix_size=args.prefix_size, - ) - - for sample_id, src_tokens, _, hypos in translations: - # Process input and grount truth - src_str = src_dict.string(src_tokens, args.remove_bpe) - - # Process top predictions - for i, hypo in enumerate(hypos[:min(len(hypos), args.nbest)]): - _, hypo_str, _ = utils.post_process_prediction( - hypo_tokens=hypo['tokens'].int().cpu(), - src_str=src_str, - alignment=hypo['alignment'].int().cpu() if hypo['alignment'] is not None else None, - align_dict=None, - tgt_dict=tgt_dict, - remove_bpe=args.remove_bpe - ) - - # Score only the top hypothesis - if i == 0: - hypo_str = tokenizer.Tokenizer.detokenize(hypo_str, 'de') - predictions.append('{}\t{}'.format(sample_id, hypo_str)) - - if args.distributed_world_size > 1: - predictions = _all_gather_predictions(predictions) - - with open(os.path.join(args.data, ref_file), 'r') as reference: - refs = [reference.readlines()] - # reducing indexed predictions as strings is more memory efficient than reducing tuples - predictions = [tuple(item.split('\t')) for item in predictions] - predictions = [(int(item[0]), item[1]) for item in predictions] - predictions.sort(key=lambda tup: tup[0]) - predictions = [hypo[1] + ('\n' if hypo[1][-1] != '\n' else '') for hypo in predictions] - sacrebleu_score = sacrebleu.corpus_bleu(predictions, refs, lowercase=not args.test_cased_bleu).score - - if args.save_predictions: - os.makedirs(os.path.join(args.save_dir, 'predictions'), exist_ok=True) - fname = ref_file + '.pred.update_{}'.format(trainer.get_num_updates()) - save_path = os.path.join(args.save_dir, 'predictions', fname) - with open(save_path, 'w') as f: - f.write(''.join(predictions)) - - DLLogger.log(step=trainer.get_num_updates(), - data={'inference tokens/s': float(args.distributed_world_size) / gen_timer.avg}, - verbosity=0) - DLLogger.flush() - if gen_timer.sum != 0: - print('| Translated {} sentences ({} tokens) in {:.1f}s ({:.2f} sentences/s, {:.2f} tokens/s)'.format( - len(predictions), - gen_timer.n, - gen_timer.sum, - len(predictions) / gen_timer.sum, - float(args.distributed_world_size)/gen_timer.avg - )) - - print('| Eval completed in: {:.2f}s | {}CASED BLEU {:.2f}'.format( - time.time()-begin, - '' if args.test_cased_bleu else 'UN', - sacrebleu_score - )) - - return sacrebleu_score - -def _all_gather_predictions(predictions): - ready = False - all_ready = False - reduced_predictions = [] - max_size = 65000 - while not all_ready: - lst_len = len(predictions) - size = 2000 # some extra space for python stuff - n = 0 - while n < lst_len: - str_len = len(predictions[n].encode('utf8')) + 8 # per string pickle overhead - if size + str_len >= max_size: - break - size += str_len - n += 1 - chunk = predictions[:n] - predictions = predictions[n:] - if not predictions: - ready = True - chunk = (ready, chunk) - torch.cuda.synchronize() - gathered = distributed_utils.all_gather_list(chunk, max_size=65000) - torch.cuda.synchronize() - reduced_predictions += [t[1] for t in gathered] - all_ready = all([t[0] for t in gathered]) - - reduced_predictions = [item for sublist in reduced_predictions for item in sublist] - - return reduced_predictions - - -def save_checkpoint(args, trainer, epoch_itr, val_loss): - if epoch_itr.epoch % args.save_interval != 0: - return - if args.no_save or not distributed_utils.is_master(args): - return - epoch = epoch_itr.epoch - end_of_epoch = epoch_itr.end_of_epoch() - - checkpoint_conds = collections.OrderedDict() - checkpoint_conds['checkpoint{}.pt'.format(epoch)] = end_of_epoch and not args.no_epoch_checkpoints - checkpoint_conds['checkpoint_best.pt'] = ( - val_loss is not None and - (not hasattr(save_checkpoint, 'best') or val_loss < save_checkpoint.best) - ) - checkpoint_conds['checkpoint_last.pt'] = True # keep this last so that it's a symlink - - prev_best = getattr(save_checkpoint, 'best', val_loss) - if val_loss is not None: - save_checkpoint.best = min(val_loss, prev_best) - extra_state = { - 'best': save_checkpoint.best, - 'train_iterator': epoch_itr.state_dict(), - 'val_loss': val_loss, - } - extra_state.update(save_checkpoint.extra_items) - - checkpoints = [os.path.join(args.save_dir, 'checkpoints', fn) - for fn, cond in checkpoint_conds.items() if cond] - if checkpoints: - for cp in checkpoints: - trainer.save_checkpoint(cp, extra_state) - - -def add_extra_items_to_checkpoint(items): - if not hasattr(save_checkpoint, 'extra_items'): - save_checkpoint.extra_items = {} - save_checkpoint.extra_items.update(items) - -def load_checkpoint(args, trainer, epoch_itr): - """Load a checkpoint and replay dataloader to match.""" - os.makedirs(os.path.join(args.save_dir, 'checkpoints'), exist_ok=True) - checkpoint_path = os.path.join(args.save_dir, 'checkpoints', args.restore_file) - if os.path.isfile(checkpoint_path): - extra_state = trainer.load_checkpoint(checkpoint_path) - if extra_state is not None: - # replay train iterator to match checkpoint - epoch_itr.load_state_dict(extra_state['train_iterator']) - - print('| loaded checkpoint {} (epoch {} @ {} updates)'.format( - checkpoint_path, epoch_itr.epoch, trainer.get_num_updates())) - - trainer.lr_step(epoch_itr.epoch) - trainer.lr_step_update(trainer.get_num_updates()) - if 'best' in extra_state: - save_checkpoint.best = extra_state['best'] - - -if __name__ == '__main__': - parser = options.get_training_parser() - ARGS = options.parse_args_and_arch(parser) - - if ARGS.distributed_world_size > 1: - distributed_utils.distributed_init(ARGS) - - main(ARGS) diff --git a/PyTorch/NLP/Transformer/transformer.png b/PyTorch/NLP/Transformer/transformer.png deleted file mode 100644 index 2bfca656cd9cd4f3d78bbffb500097f4efb0b5ee..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 196304 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%0DT@-~R7;{kraLT(X+# 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 $BASH_ENV + source $BASH_ENV + if [ ! -d ~/miniconda/envs/fairseq ] + then + conda create -y -n fairseq python=3.8 + fi + source activate fairseq + python --version + pip install --upgrade pip +# ------------------------------------------------------------------------------------- +# Jobs to run +# ------------------------------------------------------------------------------------- + +jobs: + + gpu_tests_pt19: + <<: *gpu + + working_directory: ~/fairseq-py + + steps: + - checkout + - <<: *check_nvidia_driver + - <<: *create_conda_env + - restore_cache: + key: *cache_key + - <<: *install_dep_pt19 + - <<: *install_dep_common + - <<: *install_dep_fused_ops + - save_cache: + paths: + - ~/miniconda/ + key: *cache_key + - <<: *install_repo + - <<: *run_unittests + + gpu_tests_pt18: + <<: *gpu + + working_directory: ~/fairseq-py + + steps: + - checkout + - <<: *check_nvidia_driver + - <<: *create_conda_env + - restore_cache: + key: *cache_key + - <<: *install_dep_pt18 + - <<: *install_dep_common + - <<: *install_dep_fused_ops + - save_cache: + paths: + - ~/miniconda/ + key: *cache_key + - <<: *install_repo + - <<: *run_unittests + +workflows: + version: 2 + build: + jobs: + - gpu_tests_pt18 + - gpu_tests_pt19 diff --git a/PyTorch/NLP/new-Transformer/.github/CODEOWNERS b/PyTorch/NLP/new-Transformer/.github/CODEOWNERS new file mode 100644 index 00000000..4e818c6f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/CODEOWNERS @@ -0,0 +1,18 @@ +# Setting up CODEOWNERS for UST related codebase +# Documentation for open sourced models relevant to UST +examples/speech_to_text @kahne @sravyapopuri388 @jmp84 +examples/speech_to_speech @an918tw @sravyapopuri388 @jmp84 +examples/speech_synthesis @kahne @jmp84 +examples/simultaneous_translation @kahne @jmp84 +examples/speech_text_joint_to_text @yuntang @jmp84 + +# Speech related models relevant to UST +fairseq/models/speech_to_speech @sravyapopuri388 @jmp84 +fairseq/models/speech_to_text @kahne @sravyapopuri388 @jmp84 +fairseq/models/text_to_speech @kahne @jmp84 + +# CONFORMER IMPLEMENTATION +fairseq/modules/conformer_layer.py @sravyapopuri388 @jmp84 +fairseq/modules/espnet_multihead_attention.py @sravyapopuri388 @jmp84 +fairseq/modules/rotary_positional_embedding.py @sravyapopuri388 @jmp84 +fairseq/modules/positional_encoding.py @sravyapopuri388 @jmp84 diff --git a/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE.md b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE.md new file mode 100644 index 00000000..5c4c4493 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,3 @@ +## 👉 [Please follow one of these issue templates](https://github.com/pytorch/fairseq/issues/new/choose) 👈 + +Note: to keep the backlog clean and actionable, issues may be immediately closed if they do not follow one of the above issue templates. diff --git a/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/bug_report.md b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..aa15123d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,43 @@ +--- +name: 🐛 Bug Report +about: Submit a bug report to help us improve +labels: 'bug, needs triage' +--- + +## 🐛 Bug + + + +### To Reproduce + +Steps to reproduce the behavior (**always include the command you ran**): + +1. Run cmd '....' +2. See error + + + + +#### Code sample + + +### Expected behavior + + + +### Environment + + - fairseq Version (e.g., 1.0 or main): + - PyTorch Version (e.g., 1.0) + - OS (e.g., Linux): + - How you installed fairseq (`pip`, source): + - Build command you used (if compiling from source): + - Python version: + - CUDA/cuDNN version: + - GPU models and configuration: + - Any other relevant information: + +### Additional context + + diff --git a/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/documentation.md b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/documentation.md new file mode 100644 index 00000000..3a6e2e9e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/documentation.md @@ -0,0 +1,15 @@ +--- +name: 📚 Documentation/Typos +about: Report an issue related to documentation or a typo +labels: 'documentation, needs triage' +--- + +## 📚 Documentation + +For typos and doc fixes, please go ahead and: + +1. Create an issue. +2. Fix the typo. +3. Submit a PR. + +Thanks! diff --git a/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/feature_request.md b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..93c86680 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,24 @@ +--- +name: 🚀 Feature Request +about: Submit a proposal/request for a new feature +labels: 'enhancement, help wanted, needs triage' +--- + +## 🚀 Feature Request + + +### Motivation + + + +### Pitch + + + +### Alternatives + + + +### Additional context + + diff --git a/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/how-to-question.md b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/how-to-question.md new file mode 100644 index 00000000..04f3f15d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/ISSUE_TEMPLATE/how-to-question.md @@ -0,0 +1,33 @@ +--- +name: ❓ Questions/Help +about: If you have questions, please first search existing issues and docs +labels: 'question, needs triage' +--- + +## ❓ Questions and Help + +### Before asking: +1. search the issues. +2. search the docs. + + + +#### What is your question? + +#### Code + + + +#### What have you tried? + +#### What's your environment? + + - fairseq Version (e.g., 1.0 or main): + - PyTorch Version (e.g., 1.0) + - OS (e.g., Linux): + - How you installed fairseq (`pip`, source): + - Build command you used (if compiling from source): + - Python version: + - CUDA/cuDNN version: + - GPU models and configuration: + - Any other relevant information: diff --git a/PyTorch/NLP/new-Transformer/.github/PULL_REQUEST_TEMPLATE.md b/PyTorch/NLP/new-Transformer/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..d005e2df --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,16 @@ +# Before submitting + +- [ ] Was this discussed/approved via a Github issue? (no need for typos, doc improvements) +- [ ] Did you read the [contributor guideline](https://github.com/pytorch/fairseq/blob/main/CONTRIBUTING.md)? +- [ ] Did you make sure to update the docs? +- [ ] Did you write any new necessary tests? + +## What does this PR do? +Fixes # (issue). + +## PR review +Anyone in the community is free to review the PR once the tests have passed. +If we didn't discuss your PR in Github issues there's a high chance it will not be merged. + +## Did you have fun? +Make sure you had fun coding 🙃 diff --git a/PyTorch/NLP/new-Transformer/.github/stale.yml b/PyTorch/NLP/new-Transformer/.github/stale.yml new file mode 100644 index 00000000..b12867da --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/stale.yml @@ -0,0 +1,30 @@ +# Configuration for probot-stale - https://github.com/probot/stale +# Mostly copied from github.com/facebook/react/blob/master/.github/stale.yml +# Number of days of inactivity before an issue becomes stale +daysUntilStale: 90 +# Number of days of inactivity before a stale issue is closed +daysUntilClose: 7 +# Issues with these labels will never be considered stale +exemptLabels: + - bug +# Label to use when marking an issue as stale +staleLabel: stale +issues: + # Comment to post when marking an issue as stale. + markComment: > + This issue has been automatically marked as stale. + **If this issue is still affecting you, please leave any comment** (for example, "bump"), and we'll keep it open. + We are sorry that we haven't been able to prioritize it yet. If you have any new additional information, please include it with your comment! + # Comment to post when closing a stale issue. + closeComment: > + Closing this issue after a prolonged period of inactivity. If this issue is still present in the latest release, please create a new issue with up-to-date information. Thank you! +pulls: + # Comment to post when marking a pull request as stale. + markComment: > + This pull request has been automatically marked as stale. + **If this pull request is still relevant, please leave any comment** (for example, "bump"), and we'll keep it open. + We are sorry that we haven't been able to prioritize reviewing it yet. Your contribution is very much appreciated. + # Comment to post when closing a stale pull request. + closeComment: > + Closing this pull request after a prolonged period of inactivity. If this issue is still present in the latest release, please ask for this pull request to be reopened. Thank you! + diff --git a/PyTorch/NLP/new-Transformer/.github/workflows/build.yml b/PyTorch/NLP/new-Transformer/.github/workflows/build.yml new file mode 100644 index 00000000..a14365cd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/workflows/build.yml @@ -0,0 +1,62 @@ +name: build + +on: + # Trigger the workflow on push to main or any pull request + push: + branches: + - main + pull_request: + +jobs: + build: + + strategy: + max-parallel: 4 + matrix: + platform: [ubuntu-latest, macos-latest] + python-version: [3.8, 3.9] + + runs-on: ${{ matrix.platform }} + + steps: + - uses: actions/checkout@v2 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v2 + with: + python-version: ${{ matrix.python-version }} + + - name: Conditionally install pytorch + if: matrix.platform == 'windows-latest' + run: pip3 install torch -f https://download.pytorch.org/whl/torch_stable.html + + - name: Install locally + run: | + python -m pip install --upgrade pip + git submodule update --init --recursive + python setup.py build_ext --inplace + python -m pip install --editable . + + - name: Install optional test requirements + run: | + python -m pip install iopath transformers pyarrow + python -m pip install git+https://github.com/facebookresearch/fairscale.git@main + python -m pip install --progress-bar off git+https://github.com/facebookresearch/xformers.git@main + python -m pip install pytest + + - name: Lint with flake8 + run: | + pip install flake8 + # stop the build if there are Python syntax errors or undefined names + flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics --extend-exclude fairseq/model_parallel/megatron + # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide + flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics --extend-exclude fairseq/model_parallel/megatron + + - name: Run tests + run: | + python setup.py test + + - name: Lint with black + run: | + pip install black==22.3.0 + black --check . --extend-exclude 'examples|fairseq\/model_parallel\/megatron' diff --git a/PyTorch/NLP/new-Transformer/.github/workflows/build_wheels.yml b/PyTorch/NLP/new-Transformer/.github/workflows/build_wheels.yml new file mode 100644 index 00000000..acd828e8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.github/workflows/build_wheels.yml @@ -0,0 +1,49 @@ +name: build_wheels + +on: + push: + branches: + - v[0-9]+.[0-9]+.[x0-9]+ + tags: + - v* + +jobs: + build_wheels: + name: Build wheels on ${{ matrix.os }} + runs-on: ${{ matrix.os }} + strategy: + matrix: + os: [ubuntu-latest, macos-latest] + + steps: + - uses: actions/checkout@v2 + + - name: Install Python + uses: actions/setup-python@v2 + with: + python-version: '3.8' + + - name: Upgrade pip + run: | + python3 -m pip install --upgrade pip + + - name: Install cibuildwheel + run: | + python3 -m pip install cibuildwheel + + - name: Build wheels for CPython + run: | + python3 -m cibuildwheel --output-dir dist + env: + CIBW_BUILD: "cp36-*64 cp37-*64 cp38-*64" + CIBW_MANYLINUX_X86_64_IMAGE: manylinux1 + CIBW_BEFORE_BUILD: git submodule update --init --recursive && pip install . + # Install system library + CIBW_BEFORE_BUILD_LINUX: yum install -y libffi-devel || apt-get install -y libffi-devel || apk add --update --no-cache libffi-devel || true + CIBW_ENVIRONMENT: "PIP_ONLY_BINARY=numpy" + CIBW_SKIP: "*musllinux*" + + - uses: actions/upload-artifact@v2 + with: + name: wheels + path: ./dist/*.whl diff --git a/PyTorch/NLP/new-Transformer/.gitignore b/PyTorch/NLP/new-Transformer/.gitignore new file mode 100644 index 00000000..4be13638 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.gitignore @@ -0,0 +1,141 @@ +# JetBrains PyCharm IDE +.idea/ + +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# macOS dir files +.DS_Store + +# Distribution / packaging +.Python +env/ +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# Checkpoints +checkpoints + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +.hypothesis/ + +# Translations +*.mo +*.pot + +# Django stuff: +*.log +local_settings.py + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# celery beat schedule file +celerybeat-schedule + +# SageMath parsed files +*.sage.py + +# dotenv +.env + +# virtualenv +.venv +venv/ +ENV/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ + +# Generated files +/fairseq/temporal_convolution_tbc +/fairseq/modules/*_layer/*_forward.cu +/fairseq/modules/*_layer/*_backward.cu +/fairseq/version.py + +# data +data-bin/ + +# reranking +/examples/reranking/rerank_data + +# Cython-generated C++ source files +/fairseq/data/data_utils_fast.cpp +/fairseq/data/token_block_utils_fast.cpp + +# VSCODE +.vscode/ftp-sync.json +.vscode/settings.json + +# Experimental Folder +experimental/* + +# Weights and Biases logs +wandb/ + +# Hydra artifacts +nohup.out +multirun +outputs diff --git a/PyTorch/NLP/new-Transformer/.gitmodules b/PyTorch/NLP/new-Transformer/.gitmodules new file mode 100644 index 00000000..07a55d45 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.gitmodules @@ -0,0 +1,4 @@ +[submodule "fairseq/model_parallel/megatron"] + path = fairseq/model_parallel/megatron + url = https://github.com/ngoyal2707/Megatron-LM + branch = fairseq diff --git a/PyTorch/NLP/new-Transformer/.isort.cfg b/PyTorch/NLP/new-Transformer/.isort.cfg new file mode 100644 index 00000000..aed482f4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.isort.cfg @@ -0,0 +1,2 @@ +[settings] +known_third_party = _cffi_backend,agg_results,aml,bitarray,boto3,botocore,dump_hubert_feature,dynamicconv_cuda,editdistance,faiss,fasttext,feature_utils,ffmpeg,g2p_en,h5py,hydra,hypothesis,indicnlp,inflect,iopath,joblib,kaldi_io,kenlm,libfb,librosa,lightconv_cuda,matplotlib,misc,mmpt,mmpt_cli,model,nltk,npy_append_array,numpy,omegaconf,pandas,pathbuilder,preprocessing,progressbar,pythainlp,random_sequence_shuffler,regex,sacrebleu,sacremoses,scipy,sentencepiece,setuptools,six,sklearn,soundfile,sweep,sweep_wmt_en2de_transformer_big_common,tabulate,torch,torchaudio,tqdm,unidecode,utils,videoreader,wav2vec_cluster_faiss,wget,yaml diff --git a/PyTorch/NLP/new-Transformer/.pre-commit-config.yaml b/PyTorch/NLP/new-Transformer/.pre-commit-config.yaml new file mode 100644 index 00000000..6b1d6aed --- /dev/null +++ b/PyTorch/NLP/new-Transformer/.pre-commit-config.yaml @@ -0,0 +1,40 @@ +exclude: 'build|stubs' + +default_language_version: + python: python3 + +repos: +- repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.1.0 + hooks: + - id: trailing-whitespace + - id: check-ast + - id: check-merge-conflict + - id: no-commit-to-branch + args: ['--branch=master'] + - id: check-added-large-files + args: ['--maxkb=500'] + - id: end-of-file-fixer + +- repo: https://github.com/ambv/black + rev: 22.3.0 + hooks: + - id: black + language_version: python3.8 + +- repo: https://gitlab.com/pycqa/flake8 + rev: 3.9.2 + hooks: + - id: flake8 + args: [ + # only error for syntax errors and undefined names + "--select=E9,F63,F7,F82", + ] + +- repo: https://github.com/pycqa/isort + rev: 5.10.1 + hooks: + - id: isort + exclude: README.md + additional_dependencies: [toml] + args: ["--profile", "black"] diff --git a/PyTorch/NLP/new-Transformer/CODE_OF_CONDUCT.md b/PyTorch/NLP/new-Transformer/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..a0cbeaab --- /dev/null +++ b/PyTorch/NLP/new-Transformer/CODE_OF_CONDUCT.md @@ -0,0 +1,77 @@ +# Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project and +our community a harassment-free experience for everyone, regardless of age, body +size, disability, ethnicity, sex characteristics, gender identity and expression, +level of experience, education, socio-economic status, nationality, personal +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention or + advances +* Trolling, insulting/derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of acceptable +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropriate, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces, and it also applies when +an individual is representing the project or its community in public spaces. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, or acting +as an appointed representative at an online or offline event. Representation of +a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at . All +complaints will be reviewed and investigated and will result in a response that +is deemed necessary and appropriate to the circumstances. The project team is +obligated to maintain confidentiality with regard to the reporter of an incident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in good +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq + diff --git a/PyTorch/NLP/new-Transformer/CONTRIBUTING.md b/PyTorch/NLP/new-Transformer/CONTRIBUTING.md new file mode 100644 index 00000000..60e90258 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/CONTRIBUTING.md @@ -0,0 +1,82 @@ +# Contributing to Facebook AI Research Sequence-to-Sequence Toolkit (fairseq) +We want to make contributing to this project as easy and transparent as +possible. + +## Pull Requests +We actively welcome your pull requests. + +1. Fork the repo and create your branch from `main`. +2. If you've added code that should be tested, add tests. +3. If you've changed APIs, update the documentation. +4. Ensure the test suite passes. +5. Make sure your code lints. +6. If you haven't already, complete the Contributor License Agreement ("CLA"). + +## Contributor License Agreement ("CLA") +In order to accept your pull request, we need you to submit a CLA. You only need +to do this once to work on any of Facebook's open source projects. + +Complete your CLA here: + +## Issues +We use GitHub issues to track public bugs. Please ensure your description is +clear and has sufficient instructions to be able to reproduce the issue. + +## License +By contributing to Facebook AI Research Sequence-to-Sequence Toolkit (fairseq), +you agree that your contributions will be licensed under the LICENSE file in +the root directory of this source tree. + +## Pre-commit hooks +In order to ensure your code lints, there are pre-commit hooks configured in the repository which you can install. +After installation, they will automatically run each time you commit. +An abbreviated guide is given below; for more information, refer to [the offical pre-commit documentation](https://pre-commit.com/). + +### Installation +``` +pip install pre-commit +pre-commit install +``` + +### Usage +Just commit your changes: +``` +git commit -m "My informative commit message" +``` + +If there was a failure, you will get feedback +``` +[INFO] Initializing environment for https://github.com/PyCQA/flake8. +[INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks. +[INFO] Once installed this environment will be reused. +[INFO] This may take a few minutes... +[INFO] Installing environment for https://github.com/PyCQA/flake8. +[INFO] Once installed this environment will be reused. +[INFO] This may take a few minutes... +Trim Trailing Whitespace.................................................Failed +- hook id: trailing-whitespace +- exit code: 1 +- files were modified by this hook +Fixing examples/nllb/modeling/wmt15_benchmark/eval_langs2.sh +Fix End of Files.........................................................Failed +- hook id: end-of-file-fixer +- exit code: 1 +- files were modified by this hook +Fixing examples/few_shot/scripts/schedule_jobs_few_shot.py +flake8...................................................................Passed +``` + +Certain hooks modify your files to comply. +To include these modifications, you will need to add them (i.e. `git add ...`) and commit again. + +If all is well, you should see something like: +``` +Trim Trailing Whitespace.................................................Passed +Fix End of Files.........................................................Passed +flake8...................................................................Passed +[gshard-fix-ci 8698644e1] Fix lint, add pre-commit hooks + 10 files changed, 148 insertions(+), 110 deletions(-) + create mode 100644 .flake8 + create mode 100644 .pre-commit-config.yaml + rename examples/nllb/modeling/wmt15_benchmark/{eval_langs2.py => eval_langs2.sh} (99%) + ``` diff --git a/PyTorch/NLP/new-Transformer/LICENSE b/PyTorch/NLP/new-Transformer/LICENSE new file mode 100644 index 00000000..b96dcb04 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) Facebook, Inc. and its affiliates. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/PyTorch/NLP/new-Transformer/README.md b/PyTorch/NLP/new-Transformer/README.md new file mode 100644 index 00000000..53ed48a8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/README.md @@ -0,0 +1,442 @@ +### 1.Benchmark下载地址 + +transformer：https://github.com/pytorch/fairseq.git + +最新的githup上代码和现在存在区别，最好使用本地旧版本代码，否则可能出现HIP版本的torch不识别情况 + +### 2.1 数据集准备 + +``` +环境准备： + +pip3 install fastBPE sacremoses subword_nmt + +数据集下载： + +cd examples/translation/ + +bash prepare-wmt14en2de.sh --icml17 + +数据预处理： + +DATA_DIR=~/data/wmt14_en_de_joined_dict + +TEXT=`pwd`/examples/translation/wmt14_en_de + +fairseq-preprocess --source-lang en --target-lang de --trainpref $TEXT/train --validpref $TEXT/valid --testpref $TEXT/test --destdir $DATA_DIR --nwordssrc 32768 --nwordstgt 32768 --joined-dictionary --workers 20 + +相关参数说明： + +--source-lang source language + +--target-lang target language + +--trainpref rain file prefix (also used to build dictionaries) + +--validpref comma separated, valid file prefixes (words missing from train set are replaced with ) + +--testpref comma separated, test file prefixes (words missing from train set are replaced with ) + +--destdir destination dir, Default: “data-bin” + +数据集路径： + +DATA_PATH=~/data/wmt14_en_de_joined_dict +``` + + + +#### 2.2.环境部署 + +##### 2.2.1.构建测试的虚拟环境 + +``` +virtualenv -p python3 venv + +source venv/bin/activate +``` + +##### 2.2.2.安装python3.7环境下的依赖包 + +``` +pip3 install --upgrade pip + +pip3 install typing + +pip3 install sacremoses + +pip3 install numpy + +pip3 install torch-1.10.0a0+gitd8cde89.atomic.dtk22042-cp37-cp37m-linux_x86_64.whl + +pip3 install apex-0.1_dtk22.04-cp37-cp37m-linux_x86_64.whl + +pip3 install setuptools==59.5.0 + +pip3 install protobuf==3.20.0 +``` + +##### 2.2.3.安装fairseq + +``` +#git clone https://github.com/pytorch/fairseq.git +#cd fairseq +#整个transformer文件夹就是从github上拷贝下来的fariseq，可以直接安装 +pip3 install --editable ./ + +相关说明：可以先把setup.py里的torch、torch-audio的安装屏蔽掉 +``` + +##### 2.2.4.环境变量里设置env.sh + +``` +WORK_PATH=`pwd` +source env.sh +``` + +### 3.transformer测试（昆山） + +#### 3.1.单卡测试（单精度） + +##### 3.1.1.run.sh + +``` + +export HSA_FORCE_FINE_GRAIN_PCIE=1 +export MIOPEN_FIND_MODE=1 +export HIP_VISIBLE_DEVICES=0 +export TOKEN=2560 +export DATA_PATH=~/data/wmt14_en_de_joined_dict + +export HIP_LAUNCH_BLOCKING=1 +export ROCBLAS_ATOMICS_MOD=1 +python3 train.py \ + $DATA_PATH \ + --arch transformer_wmt_en_de \ + --share-decoder-input-output-embed \ + --optimizer adam \ + --adam-betas '(0.9, 0.98)' \ + --clip-norm 0.0 \ + --lr 5e-4 \ + --lr-scheduler inverse_sqrt \ + --warmup-updates 4000 \ + --dropout 0.3 \ + --weight-decay 0.0001 \ + --criterion label_smoothed_cross_entropy \ + --label-smoothing 0.1 \ + --max-tokens ${TOKEN} \ + --eval-bleu \ + --eval-bleu-args '{"beam": 5, "max_len_a": 1.2, "max_len_b": 10}' \ + --eval-bleu-detok moses \ + --eval-bleu-remove-bpe \ + --eval-bleu-print-samples \ + --best-checkpoint-metric bleu \ + --maximize-best-checkpoint-metric \ + --max-epoch 1 + +``` + +##### 3.1.2.运行 +``` +./ run.sh +``` + +#### 3.2.四卡测试（单精度） + +##### 3.2.1.single_process.sh + +``` +#!/bin/bash + +export MIOPEN_DEBUG_DISABLE_FIND_DB=1 + +export NCCL_SOCKET_IFNAME=eno1 + +export HSA_USERPTR_FOR_PAGED_MEM=0 + +lrank=$OMPI_COMM_WORLD_LOCAL_RANK + +comm_rank=$OMPI_COMM_WORLD_RANK + +comm_size=$OMPI_COMM_WORLD_SIZE + +TOKENS=2560 + +DATA_PATH=~/fairseq/examples/translation/data-bin/wmt14_en_de_joined_dict + +APP="python3 ~/fairseq/train.py $DATA_PATH --arch transformer_wmt_en_de --share-decoder-input-output-embed --optimizer adam --adam-betas (0.9,0.98) --clip-norm 0.0 --lr 5e-4 --lr-scheduler inverse_sqrt --warmup-updates 4000 --dropout 0.3 --weight-decay 0.0001 --criterion label_smoothed_cross_entropy --label-smoothing 0.1 --max-tokens $TOKENS --eval-bleu --eval-bleu-args {\"beam\":5,\"max_len_a\":1.2,\"max_len_b\":10} --eval-bleu-detok moses --eval-bleu-remove-bpe --eval-bleu-print-samples --best-checkpoint-metric bleu --maximize-best-checkpoint-metric --distributed-rank ${comm_rank} --distributed-world-size ${comm_size} --device-id ${lrank} --local_rank ${lrank} --distributed-init-method tcp://${1}:34567 --distributed-no-spawn --max-epoch 1" + +case ${lrank} in + +[0]) + + export HIP_VISIBLE_DEVICES=0,1,2,3 + + export UCX_NET_DEVICES=mlx5_0:1 + + export UCX_IB_PCI_BW=mlx5_0:50Gbs + + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + + ;; + +[1]) + + export HIP_VISIBLE_DEVICES=0,1,2,3 + + export UCX_NET_DEVICES=mlx5_1:1 + + export UCX_IB_PCI_BW=mlx5_1:50Gbs + + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + + ;; + +[2]) + + export HIP_VISIBLE_DEVICES=0,1,2,3 + + export UCX_NET_DEVICES=mlx5_2:1 + + export UCX_IB_PCI_BW=mlx5_2:50Gbs + + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + + ;; + +[3]) + + export HIP_VISIBLE_DEVICES=0,1,2,3 + + export UCX_NET_DEVICES=mlx5_3:1 + + export UCX_IB_PCI_BW=mlx5_3:50Gbs + + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + + ;; + +esac +``` + +##### 3.2.2.run4.sh + +``` +#!/usr/bin/env bash +#SBATCH -J distribute +#SBATCH -p wzhdtest +#SBATCH -N 1 +#SBARCH -n 32 +#SBATCH --ntasks-per-node=4 +#SBATCH --cpus-per-task=8 +#SBATCH --gres=dcu:4 +set -x +hostfile=./$SLURM_JOB_ID +scontrol show hostnames $SLURM_JOB_NODELIST > ${hostfile} +for i in `cat $hostfile` +do + echo ${i} slots=4 >> `pwd`/hostfile-$SLURM_JOB_ID + ((num_node=${num_node}+1)) +done +num_dcu=$((${num_node}*4)) +echo $num_dcu +nodename=$(cat $hostfile |sed -n "1p") +echo $nodename +dist_url=`echo $nodename | awk '{print $1}'` +export HSA_USERPTR_FOR_PAGED_MEM=0 +mpirun -np ${num_dcu} --hostfile hostfile-$SLURM_JOB_ID single_process.sh $dist_url +``` + +##### 3.2.3.运行 +``` +sbatch run4.sh +``` + +##### 3.2.4.参数说明 + +- 上面的中single_process.sh需要关注--max-tokens； +- 通过--arch 设置要测试的网络，eg:transformer_wmt_en_de 等； +- 上述 run_transformer_4dcus.sh中mpirun 运行命令表示使用4张DCU加速卡训练。 + +#### 3.3.单卡测试（半精度） + +##### 3.3.1.fp16_run_transformer.sh + +``` +export HSA_FORCE_FINE_GRAIN_PCIE=1 +export MIOPEN_FIND_MODE=1 +export HIP_VISIBLE_DEVICES=0 +export DATA_PATH=~/data/wmt14_en_de_joined_dict +export TOKEN=2560 +python3 train.py \ + $DATA_PATH \ + --save-dir module-fp16_2560 \ + --arch transformer_wmt_en_de --share-decoder-input-output-embed \ + --optimizer adam --adam-betas '(0.9, 0.98)' --clip-norm 0.0 \ + --lr 5e-4 --lr-scheduler inverse_sqrt --warmup-updates 4000 \ + --dropout 0.3 --weight-decay 0.0001 \ + --criterion label_smoothed_cross_entropy --label-smoothing 0.1 \ + --max-tokens ${TOKEN} \ + --eval-bleu \ + --eval-bleu-args '{"beam": 5, "max_len_a": 1.2, "max_len_b": 10}' \ + --eval-bleu-detok moses \ + --eval-bleu-remove-bpe \ + --eval-bleu-print-samples \ + --best-checkpoint-metric bleu --maximize-best-checkpoint-metric --max-epoch 1 --fp16 +``` + +##### 3.3.2.运行 + +./ fp16_run_transformer.sh + +##### 3.3.3.参数说明 + +--max-tokens 根据tokens设置batch size + +--fp16 使用半精度训练 + +#### 3.4.四卡测试（半精度） + +##### 3.4.1.fp16_single_process.sh + +``` + +export HIP_VISIBLE_DEVICES=0 +export MIOPEN_DEBUG_DISABLE_FIND_DB=1 +export NCCL_SOCKET_IFNAME=eno1 +export HSA_USERPTR_FOR_PAGED_MEM=0 +lrank=$OMPI_COMM_WORLD_LOCAL_RANK +comm_rank=$OMPI_COMM_WORLD_RANK +comm_size=$OMPI_COMM_WORLD_SIZE +TOKENS=2560 +DATA_PATH=~/data/wmt14_en_de_joined_dict +APP="python3 ~/fairseq/train.py $DATA_PATH --arch transformer_wmt_en_de --share-decoder-input-output-embed --optimizer adam --adam-betas '(0.9,0.98)' --clip-norm 0.0 --lr 5e-4 --lr-scheduler inverse_sqrt --warmup-updates 4000 --dropout 0.3 --weight-decay 0.0001 --criterion label_smoothed_cross_entropy --label-smoothing 0.1 --max-tokens $TOKENS --eval-bleu --eval-bleu-args {\"beam\":5,\"max_len_a\":1.2,\"max_len_b\":10} --eval-bleu-detok moses --eval-bleu-remove-bpe --eval-bleu-print-samples --best-checkpoint-metric bleu --maximize-best-checkpoint-metric --distributed-rank ${comm_rank} --distributed-world-size ${comm_size} --device-id ${lrank} --local_rank ${lrank} --distributed-init-method tcp://${1}:34567 --distributed-no-spawn --max-epoch 1 --fp16" +case ${lrank} in +[0]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_0:1 + export UCX_IB_PCI_BW=mlx5_0:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + ;; +[1]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_1:1 + export UCX_IB_PCI_BW=mlx5_1:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + ;; +[2]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_2:1 + export UCX_IB_PCI_BW=mlx5_2:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + ;; +[3]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_3:1 + export UCX_IB_PCI_BW=mlx5_3:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + ;; +esac +``` + +##### 3.4.2.fp16_run_transformer_4dcus.sh + +``` +#!/usr/bin/env bash +#SBATCH -J transformer +#SBATCH -p wzhdtest +#SBATCH -N 1 +#SBARCH -n 32 +#SBATCH --ntasks-per-node=4 +#SBATCH --cpus-per-task=8 +#SBATCH --gres=dcu:4 +set -x +hostfile=./$SLURM_JOB_ID +scontrol show hostnames $SLURM_JOB_NODELIST > ${hostfile} +for i in `cat $hostfile` +do + echo ${i} slots=4 >> `pwd`/hostfile-$SLURM_JOB_ID + ((num_node=${num_node}+1)) +done +num_dcu=$((${num_node}*4)) +echo $num_dcu +nodename=$(cat $hostfile |sed -n "1p") +echo $nodename +dist_url=`echo $nodename | awk '{print $1}'` +export HSA_USERPTR_FOR_PAGED_MEM=0 +mpirun -np ${num_dcu} --hostfile hostfile-$SLURM_JOB_ID single_fp16.sh $dist_ur + +``` + +##### 3.4.3.运行 + +sbatch fp16_ run_transformer_4dcus.sh + +##### 3.4.4.参数说明 + +- 上面的中single_process.sh需要关注--max-tokens； +- 通过--arch 设置要测试的网络，eg:transformer_wmt_en_de 等； +- 上述 run_transformer_4dcus.sh中mpirun 运行命令表示使用4张DCU加速卡训练。 + +#### 3.5. 部分问题说明 + +##### 3.5.1. format错误 + +报错信息如下： + +``` + File "~/virturlenv-test/venv/lib/python3.6/site-packages/sacrebleu/metrics/bleu.py", line 103, in __init__ + self._verbose += f"ratio = {self.ratio:.3f} hyp_len = {self.sys_len:d} " + ... + +ValueError: Unknown format code 'd' for object of type 'float' +``` + +修改方法：修改报错提示中的bleu.py，103和104行的d改成.0f + +``` +#修改后 +self._verbose += f"ratio = {self.ratio:.3f} hyp_len ={self.sys_len:.0f}" +self._verbose += f"ref_len = {slef.ref_len:.0f}" +``` + + + +##### 3.5.2 json格式解析错误 + +报错信息如下： + +json.decoder.JSONDecodeError: Expecting value: line 1 column 1 (char 0) + +解析错误的地方，可以看出是引号嵌套问题 + +错误的打印 + +``` +'eval_bleu_args': "'{beam:5,max_len_a:1.2,max_len_b:10}' +``` + +正确的打印 + +``` +'eval_bleu_args': '{"beam": 5, "max_len_a": 1.2, "max_len_b": 10}' +``` + +修改为： + +``` +" --eval-bleu-args {\"beam\":5,\"max_len_a\":1.2,\"max_len_b\":10}" +``` + diff --git a/PyTorch/NLP/new-Transformer/README.md-old b/PyTorch/NLP/new-Transformer/README.md-old new file mode 100644 index 00000000..a354e1b9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/README.md-old @@ -0,0 +1,239 @@ + + +-------------------------------------------------------------------------------- + +Fairseq(-py) is a sequence modeling toolkit that allows researchers and +developers to train custom models for translation, summarization, language +modeling and other text generation tasks. + +We provide reference implementations of various sequence modeling papers: + +
List of implemented papers

+ +* **Convolutional Neural Networks (CNN)** + + [Language Modeling with Gated Convolutional Networks (Dauphin et al., 2017)](examples/language_model/conv_lm/README.md) + + [Convolutional Sequence to Sequence Learning (Gehring et al., 2017)](examples/conv_seq2seq/README.md) + + [Classical Structured Prediction Losses for Sequence to Sequence Learning (Edunov et al., 2018)](https://github.com/pytorch/fairseq/tree/classic_seqlevel) + + [Hierarchical Neural Story Generation (Fan et al., 2018)](examples/stories/README.md) + + [wav2vec: Unsupervised Pre-training for Speech Recognition (Schneider et al., 2019)](examples/wav2vec/README.md) +* **LightConv and DynamicConv models** + + [Pay Less Attention with Lightweight and Dynamic Convolutions (Wu et al., 2019)](examples/pay_less_attention_paper/README.md) +* **Long Short-Term Memory (LSTM) networks** + + Effective Approaches to Attention-based Neural Machine Translation (Luong et al., 2015) +* **Transformer (self-attention) networks** + + Attention Is All You Need (Vaswani et al., 2017) + + [Scaling Neural Machine Translation (Ott et al., 2018)](examples/scaling_nmt/README.md) + + [Understanding Back-Translation at Scale (Edunov et al., 2018)](examples/backtranslation/README.md) + + [Adaptive Input Representations for Neural Language Modeling (Baevski and Auli, 2018)](examples/language_model/README.adaptive_inputs.md) + + [Lexically constrained decoding with dynamic beam allocation (Post & Vilar, 2018)](examples/constrained_decoding/README.md) + + [Transformer-XL: Attentive Language Models Beyond a Fixed-Length Context (Dai et al., 2019)](examples/truncated_bptt/README.md) + + [Adaptive Attention Span in Transformers (Sukhbaatar et al., 2019)](examples/adaptive_span/README.md) + + [Mixture Models for Diverse Machine Translation: Tricks of the Trade (Shen et al., 2019)](examples/translation_moe/README.md) + + [RoBERTa: A Robustly Optimized BERT Pretraining Approach (Liu et al., 2019)](examples/roberta/README.md) + + [Facebook FAIR's WMT19 News Translation Task Submission (Ng et al., 2019)](examples/wmt19/README.md) + + [Jointly Learning to Align and Translate with Transformer Models (Garg et al., 2019)](examples/joint_alignment_translation/README.md ) + + [Multilingual Denoising Pre-training for Neural Machine Translation (Liu et at., 2020)](examples/mbart/README.md) + + [Neural Machine Translation with Byte-Level Subwords (Wang et al., 2020)](examples/byte_level_bpe/README.md) + + [Unsupervised Quality Estimation for Neural Machine Translation (Fomicheva et al., 2020)](examples/unsupervised_quality_estimation/README.md) + + [wav2vec 2.0: A Framework for Self-Supervised Learning of Speech Representations (Baevski et al., 2020)](examples/wav2vec/README.md) + + [Generating Medical Reports from Patient-Doctor Conversations Using Sequence-to-Sequence Models (Enarvi et al., 2020)](examples/pointer_generator/README.md) + + [Linformer: Self-Attention with Linear Complexity (Wang et al., 2020)](examples/linformer/README.md) + + [Cross-lingual Retrieval for Iterative Self-Supervised Training (Tran et al., 2020)](examples/criss/README.md) + + [Deep Transformers with Latent Depth (Li et al., 2020)](examples/latent_depth/README.md) + + [Unsupervised Cross-lingual Representation Learning for Speech Recognition (Conneau et al., 2020)](https://arxiv.org/abs/2006.13979) + + [Self-training and Pre-training are Complementary for Speech Recognition (Xu et al., 2020)](https://arxiv.org/abs/2010.11430) + + [Robust wav2vec 2.0: Analyzing Domain Shift in Self-Supervised Pre-Training (Hsu, et al., 2021)](https://arxiv.org/abs/2104.01027) + + [Unsupervised Speech Recognition (Baevski, et al., 2021)](https://arxiv.org/abs/2105.11084) + + [Simple and Effective Zero-shot Cross-lingual Phoneme Recognition (Xu et al., 2021)](https://arxiv.org/abs/2109.11680) + + [VideoCLIP: Contrastive Pre-training for Zero-shot Video-Text Understanding (Xu et. al., 2021)](https://arxiv.org/pdf/2109.14084.pdf) + + [VLM: Task-agnostic Video-Language Model Pre-training for Video Understanding (Xu et. al., 2021)](https://aclanthology.org/2021.findings-acl.370.pdf) + + [NormFormer: Improved Transformer Pretraining with Extra Normalization (Shleifer et. al, 2021)](examples/normformer/README.md) +* **Non-autoregressive Transformers** + + Non-Autoregressive Neural Machine Translation (Gu et al., 2017) + + Deterministic Non-Autoregressive Neural Sequence Modeling by Iterative Refinement (Lee et al. 2018) + + Insertion Transformer: Flexible Sequence Generation via Insertion Operations (Stern et al. 2019) + + Mask-Predict: Parallel Decoding of Conditional Masked Language Models (Ghazvininejad et al., 2019) + + [Levenshtein Transformer (Gu et al., 2019)](examples/nonautoregressive_translation/README.md) +* **Finetuning** + + [Better Fine-Tuning by Reducing Representational Collapse (Aghajanyan et al. 2020)](examples/rxf/README.md) + +

+ +### What's New: +* May 2022 [Integration with xFormers](https://github.com/facebookresearch/xformers) +* December 2021 [Released Direct speech-to-speech translation code](examples/speech_to_speech/README.md) +* October 2021 [Released VideoCLIP and VLM models](examples/MMPT/README.md) +* October 2021 [Released multilingual finetuned XLSR-53 model](examples/wav2vec/README.md) +* September 2021 [`master` branch renamed to `main`](https://github.com/github/renaming). +* July 2021 [Released DrNMT code](examples/discriminative_reranking_nmt/README.md) +* July 2021 [Released Robust wav2vec 2.0 model](examples/wav2vec/README.md) +* June 2021 [Released XLMR-XL and XLMR-XXL models](examples/xlmr/README.md) +* May 2021 [Released Unsupervised Speech Recognition code](examples/wav2vec/unsupervised/README.md) +* March 2021 [Added full parameter and optimizer state sharding + CPU offloading](examples/fully_sharded_data_parallel/README.md) +* February 2021 [Added LASER training code](examples/laser/README.md) +* December 2020: [Added Adaptive Attention Span code](examples/adaptive_span/README.md) +* December 2020: [GottBERT model and code released](examples/gottbert/README.md) +* November 2020: Adopted the [Hydra](https://github.com/facebookresearch/hydra) configuration framework + * [see documentation explaining how to use it for new and existing projects](docs/hydra_integration.md) +* November 2020: [fairseq 0.10.0 released](https://github.com/pytorch/fairseq/releases/tag/v0.10.0) +* October 2020: [Added R3F/R4F (Better Fine-Tuning) code](examples/rxf/README.md) +* October 2020: [Deep Transformer with Latent Depth code released](examples/latent_depth/README.md) +* October 2020: [Added CRISS models and code](examples/criss/README.md) + +
Previous updates

+ +* September 2020: [Added Linformer code](examples/linformer/README.md) +* September 2020: [Added pointer-generator networks](examples/pointer_generator/README.md) +* August 2020: [Added lexically constrained decoding](examples/constrained_decoding/README.md) +* August 2020: [wav2vec2 models and code released](examples/wav2vec/README.md) +* July 2020: [Unsupervised Quality Estimation code released](examples/unsupervised_quality_estimation/README.md) +* May 2020: [Follow fairseq on Twitter](https://twitter.com/fairseq) +* April 2020: [Monotonic Multihead Attention code released](examples/simultaneous_translation/README.md) +* April 2020: [Quant-Noise code released](examples/quant_noise/README.md) +* April 2020: [Initial model parallel support and 11B parameters unidirectional LM released](examples/megatron_11b/README.md) +* March 2020: [Byte-level BPE code released](examples/byte_level_bpe/README.md) +* February 2020: [mBART model and code released](examples/mbart/README.md) +* February 2020: [Added tutorial for back-translation](https://github.com/pytorch/fairseq/tree/main/examples/backtranslation#training-your-own-model-wmt18-english-german) +* December 2019: [fairseq 0.9.0 released](https://github.com/pytorch/fairseq/releases/tag/v0.9.0) +* November 2019: [VizSeq released (a visual analysis toolkit for evaluating fairseq models)](https://facebookresearch.github.io/vizseq/docs/getting_started/fairseq_example) +* November 2019: [CamemBERT model and code released](examples/camembert/README.md) +* November 2019: [BART model and code released](examples/bart/README.md) +* November 2019: [XLM-R models and code released](examples/xlmr/README.md) +* September 2019: [Nonautoregressive translation code released](examples/nonautoregressive_translation/README.md) +* August 2019: [WMT'19 models released](examples/wmt19/README.md) +* July 2019: fairseq relicensed under MIT license +* July 2019: [RoBERTa models and code released](examples/roberta/README.md) +* June 2019: [wav2vec models and code released](examples/wav2vec/README.md) + +

+ +### Features: + +* multi-GPU training on one machine or across multiple machines (data and model parallel) +* fast generation on both CPU and GPU with multiple search algorithms implemented: + + beam search + + Diverse Beam Search ([Vijayakumar et al., 2016](https://arxiv.org/abs/1610.02424)) + + sampling (unconstrained, top-k and top-p/nucleus) + + [lexically constrained decoding](examples/constrained_decoding/README.md) (Post & Vilar, 2018) +* [gradient accumulation](https://fairseq.readthedocs.io/en/latest/getting_started.html#large-mini-batch-training-with-delayed-updates) enables training with large mini-batches even on a single GPU +* [mixed precision training](https://fairseq.readthedocs.io/en/latest/getting_started.html#training-with-half-precision-floating-point-fp16) (trains faster with less GPU memory on [NVIDIA tensor cores](https://developer.nvidia.com/tensor-cores)) +* [extensible](https://fairseq.readthedocs.io/en/latest/overview.html): easily register new models, criterions, tasks, optimizers and learning rate schedulers +* [flexible configuration](docs/hydra_integration.md) based on [Hydra](https://github.com/facebookresearch/hydra) allowing a combination of code, command-line and file based configuration +* [full parameter and optimizer state sharding](examples/fully_sharded_data_parallel/README.md) +* [offloading parameters to CPU](examples/fully_sharded_data_parallel/README.md) + +We also provide [pre-trained models for translation and language modeling](#pre-trained-models-and-examples) +with a convenient `torch.hub` interface: + +``` python +en2de = torch.hub.load('pytorch/fairseq', 'transformer.wmt19.en-de.single_model') +en2de.translate('Hello world', beam=5) +# 'Hallo Welt' +``` + +See the PyTorch Hub tutorials for [translation](https://pytorch.org/hub/pytorch_fairseq_translation/) +and [RoBERTa](https://pytorch.org/hub/pytorch_fairseq_roberta/) for more examples. + +# Requirements and Installation + +* [PyTorch](http://pytorch.org/) version >= 1.5.0 +* Python version >= 3.6 +* For training new models, you'll also need an NVIDIA GPU and [NCCL](https://github.com/NVIDIA/nccl) +* **To install fairseq** and develop locally: + +``` bash +git clone https://github.com/pytorch/fairseq +cd fairseq +pip install --editable ./ + +# on MacOS: +# CFLAGS="-stdlib=libc++" pip install --editable ./ + +# to install the latest stable release (0.10.x) +# pip install fairseq +``` + +* **For faster training** install NVIDIA's [apex](https://github.com/NVIDIA/apex) library: + +``` bash +git clone https://github.com/NVIDIA/apex +cd apex +pip install -v --no-cache-dir --global-option="--cpp_ext" --global-option="--cuda_ext" \ + --global-option="--deprecated_fused_adam" --global-option="--xentropy" \ + --global-option="--fast_multihead_attn" ./ +``` + +* **For large datasets** install [PyArrow](https://arrow.apache.org/docs/python/install.html#using-pip): `pip install pyarrow` +* If you use Docker make sure to increase the shared memory size either with `--ipc=host` or `--shm-size` + as command line options to `nvidia-docker run` . + +# Getting Started + +The [full documentation](https://fairseq.readthedocs.io/) contains instructions +for getting started, training new models and extending fairseq with new model +types and tasks. + +# Pre-trained models and examples + +We provide pre-trained models and pre-processed, binarized test sets for several tasks listed below, +as well as example training and evaluation commands. + +* [Translation](examples/translation/README.md): convolutional and transformer models are available +* [Language Modeling](examples/language_model/README.md): convolutional and transformer models are available + +We also have more detailed READMEs to reproduce results from specific papers: + +* [XLS-R: Self-supervised Cross-lingual Speech Representation Learning at Scale (Babu et al., 2021)](examples/wav2vec/xlsr/README.md) +* [Cross-lingual Retrieval for Iterative Self-Supervised Training (Tran et al., 2020)](examples/criss/README.md) +* [wav2vec 2.0: A Framework for Self-Supervised Learning of Speech Representations (Baevski et al., 2020)](examples/wav2vec/README.md) +* [Unsupervised Quality Estimation for Neural Machine Translation (Fomicheva et al., 2020)](examples/unsupervised_quality_estimation/README.md) +* [Training with Quantization Noise for Extreme Model Compression ({Fan*, Stock*} et al., 2020)](examples/quant_noise/README.md) +* [Neural Machine Translation with Byte-Level Subwords (Wang et al., 2020)](examples/byte_level_bpe/README.md) +* [Multilingual Denoising Pre-training for Neural Machine Translation (Liu et at., 2020)](examples/mbart/README.md) +* [Reducing Transformer Depth on Demand with Structured Dropout (Fan et al., 2019)](examples/layerdrop/README.md) +* [Jointly Learning to Align and Translate with Transformer Models (Garg et al., 2019)](examples/joint_alignment_translation/README.md) +* [Levenshtein Transformer (Gu et al., 2019)](examples/nonautoregressive_translation/README.md) +* [Facebook FAIR's WMT19 News Translation Task Submission (Ng et al., 2019)](examples/wmt19/README.md) +* [RoBERTa: A Robustly Optimized BERT Pretraining Approach (Liu et al., 2019)](examples/roberta/README.md) +* [wav2vec: Unsupervised Pre-training for Speech Recognition (Schneider et al., 2019)](examples/wav2vec/README.md) +* [Mixture Models for Diverse Machine Translation: Tricks of the Trade (Shen et al., 2019)](examples/translation_moe/README.md) +* [Pay Less Attention with Lightweight and Dynamic Convolutions (Wu et al., 2019)](examples/pay_less_attention_paper/README.md) +* [Understanding Back-Translation at Scale (Edunov et al., 2018)](examples/backtranslation/README.md) +* [Classical Structured Prediction Losses for Sequence to Sequence Learning (Edunov et al., 2018)](https://github.com/pytorch/fairseq/tree/classic_seqlevel) +* [Hierarchical Neural Story Generation (Fan et al., 2018)](examples/stories/README.md) +* [Scaling Neural Machine Translation (Ott et al., 2018)](examples/scaling_nmt/README.md) +* [Convolutional Sequence to Sequence Learning (Gehring et al., 2017)](examples/conv_seq2seq/README.md) +* [Language Modeling with Gated Convolutional Networks (Dauphin et al., 2017)](examples/language_model/README.conv.md) + +# Join the fairseq community + +* Twitter: https://twitter.com/fairseq +* Facebook page: https://www.facebook.com/groups/fairseq.users +* Google group: https://groups.google.com/forum/#!forum/fairseq-users + +# License + +fairseq(-py) is MIT-licensed. +The license applies to the pre-trained models as well. + +# Citation + +Please cite as: + +``` bibtex +@inproceedings{ott2019fairseq, + title = {fairseq: A Fast, Extensible Toolkit for Sequence Modeling}, + author = {Myle Ott and Sergey Edunov and Alexei Baevski and Angela Fan and Sam Gross and Nathan Ng and David Grangier and Michael Auli}, + booktitle = {Proceedings of NAACL-HLT 2019: Demonstrations}, + year = {2019}, +} +``` diff --git a/PyTorch/NLP/Transformer/README.md b/PyTorch/NLP/new-Transformer/README.md-old2 similarity index 100% rename from PyTorch/NLP/Transformer/README.md rename to PyTorch/NLP/new-Transformer/README.md-old2 diff --git a/PyTorch/NLP/new-Transformer/docs/Makefile b/PyTorch/NLP/new-Transformer/docs/Makefile new file mode 100644 index 00000000..c2f5b1a8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = fairseq +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/PyTorch/NLP/new-Transformer/docs/_static/theme_overrides.css b/PyTorch/NLP/new-Transformer/docs/_static/theme_overrides.css new file mode 100644 index 00000000..2a076419 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/_static/theme_overrides.css @@ -0,0 +1,9 @@ +.wy-table-responsive table td kbd { + white-space: nowrap; +} +.wy-table-responsive table td { + white-space: normal !important; +} +.wy-table-responsive { + overflow: visible !important; +} diff --git a/PyTorch/NLP/new-Transformer/docs/command_line_tools.rst b/PyTorch/NLP/new-Transformer/docs/command_line_tools.rst new file mode 100644 index 00000000..c16300ff --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/command_line_tools.rst @@ -0,0 +1,85 @@ +.. _Command-line Tools: + +Command-line Tools +================== + +Fairseq provides several command-line tools for training and evaluating models: + +- :ref:`fairseq-preprocess`: Data pre-processing: build vocabularies and binarize training data +- :ref:`fairseq-train`: Train a new model on one or multiple GPUs +- :ref:`fairseq-generate`: Translate pre-processed data with a trained model +- :ref:`fairseq-interactive`: Translate raw text with a trained model +- :ref:`fairseq-score`: BLEU scoring of generated translations against reference translations +- :ref:`fairseq-eval-lm`: Language model evaluation + + +.. _fairseq-preprocess: + +fairseq-preprocess +~~~~~~~~~~~~~~~~~~ +.. automodule:: fairseq_cli.preprocess + + .. argparse:: + :module: fairseq.options + :func: get_preprocessing_parser + :prog: fairseq-preprocess + + +.. _fairseq-train: + +fairseq-train +~~~~~~~~~~~~~ +.. automodule:: fairseq_cli.train + + .. argparse:: + :module: fairseq.options + :func: get_training_parser + :prog: fairseq-train + + +.. _fairseq-generate: + +fairseq-generate +~~~~~~~~~~~~~~~~ +.. automodule:: fairseq_cli.generate + + .. argparse:: + :module: fairseq.options + :func: get_generation_parser + :prog: fairseq-generate + + +.. _fairseq-interactive: + +fairseq-interactive +~~~~~~~~~~~~~~~~~~~ +.. automodule:: fairseq_cli.interactive + + .. argparse:: + :module: fairseq.options + :func: get_interactive_generation_parser + :prog: fairseq-interactive + + +.. _fairseq-score: + +fairseq-score +~~~~~~~~~~~~~ +.. automodule:: fairseq_cli.score + + .. argparse:: + :module: fairseq_cli.score + :func: get_parser + :prog: fairseq-score + + +.. _fairseq-eval-lm: + +fairseq-eval-lm +~~~~~~~~~~~~~~~ +.. automodule:: fairseq_cli.eval_lm + + .. argparse:: + :module: fairseq.options + :func: get_eval_lm_parser + :prog: fairseq-eval-lm diff --git a/PyTorch/NLP/new-Transformer/docs/conf.py b/PyTorch/NLP/new-Transformer/docs/conf.py new file mode 100644 index 00000000..87b0db98 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/conf.py @@ -0,0 +1,134 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# fairseq documentation build configuration file, created by +# sphinx-quickstart on Fri Aug 17 21:45:30 2018. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +import os +import sys +from fairseq import __version__ + + +# source code directory, relative to this file, for sphinx-autobuild +sys.path.insert(0, os.path.abspath("..")) + +source_suffix = [".rst"] + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.intersphinx", + "sphinx.ext.viewcode", + "sphinx.ext.napoleon", + "sphinxarg.ext", +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ["_templates"] + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "fairseq" +copyright = "Facebook AI Research (FAIR)" +author = "Facebook AI Research (FAIR)" + +github_doc_root = "https://github.com/pytorch/fairseq/tree/main/docs/" + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = __version__ +# The full version, including alpha/beta/rc tags. +release = __version__ + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" +highlight_language = "python" + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = "sphinx_rtd_theme" + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ["_static"] + +html_context = { + "css_files": [ + "_static/theme_overrides.css", # override wide tables in RTD theme + ], +} + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +# html_sidebars = { +# '**': [ +# 'about.html', +# 'navigation.html', +# 'relations.html', # needs 'show_related': True theme option to display +# 'searchbox.html', +# 'donate.html', +# ] +# } + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = { + "numpy": ("http://docs.scipy.org/doc/numpy/", None), + "python": ("https://docs.python.org/", None), + "torch": ("https://pytorch.org/docs/master/", None), +} diff --git a/PyTorch/NLP/new-Transformer/docs/criterions.rst b/PyTorch/NLP/new-Transformer/docs/criterions.rst new file mode 100644 index 00000000..d6b8ca6b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/criterions.rst @@ -0,0 +1,31 @@ +.. role:: hidden + :class: hidden-section + +.. _Criterions: + +Criterions +========== + +Criterions compute the loss function given the model and batch, roughly:: + + loss = criterion(model, batch) + +.. automodule:: fairseq.criterions + :members: + +.. autoclass:: fairseq.criterions.FairseqCriterion + :members: + :undoc-members: + +.. autoclass:: fairseq.criterions.adaptive_loss.AdaptiveLoss + :members: + :undoc-members: +.. autoclass:: fairseq.criterions.composite_loss.CompositeLoss + :members: + :undoc-members: +.. autoclass:: fairseq.criterions.cross_entropy.CrossEntropyCriterion + :members: + :undoc-members: +.. autoclass:: fairseq.criterions.label_smoothed_cross_entropy.LabelSmoothedCrossEntropyCriterion + :members: + :undoc-members: diff --git a/PyTorch/NLP/new-Transformer/docs/data.rst b/PyTorch/NLP/new-Transformer/docs/data.rst new file mode 100644 index 00000000..6a390cb3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/data.rst @@ -0,0 +1,58 @@ +.. role:: hidden + :class: hidden-section + +.. module:: fairseq.data + +Data Loading and Utilities +========================== + +.. _datasets: + +Datasets +-------- + +**Datasets** define the data format and provide helpers for creating +mini-batches. + +.. autoclass:: fairseq.data.FairseqDataset + :members: +.. autoclass:: fairseq.data.LanguagePairDataset + :members: +.. autoclass:: fairseq.data.MonolingualDataset + :members: + +**Helper Datasets** + +These datasets wrap other :class:`fairseq.data.FairseqDataset` instances and +provide additional functionality: + +.. autoclass:: fairseq.data.BacktranslationDataset + :members: +.. autoclass:: fairseq.data.ConcatDataset + :members: +.. autoclass:: fairseq.data.ResamplingDataset + :members: +.. autoclass:: fairseq.data.RoundRobinZipDatasets + :members: +.. autoclass:: fairseq.data.TransformEosDataset + :members: + + +Dictionary +---------- + +.. autoclass:: fairseq.data.Dictionary + :members: + + +Iterators +--------- + +.. autoclass:: fairseq.data.CountingIterator + :members: +.. autoclass:: fairseq.data.EpochBatchIterator + :members: +.. autoclass:: fairseq.data.GroupedIterator + :members: +.. autoclass:: fairseq.data.ShardedIterator + :members: diff --git a/PyTorch/NLP/new-Transformer/docs/docutils.conf b/PyTorch/NLP/new-Transformer/docs/docutils.conf new file mode 100644 index 00000000..526acffd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/docutils.conf @@ -0,0 +1,2 @@ +[writers] +option-limit=0 diff --git a/PyTorch/NLP/new-Transformer/docs/fairseq.gif b/PyTorch/NLP/new-Transformer/docs/fairseq.gif new file mode 100644 index 0000000000000000000000000000000000000000..5782fdbc7e0014564725c3ad0fc6be5c6bcd9983 GIT binary patch literal 2664833 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�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

O3Pl|?VP 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ΠAznjaOh#2|x8 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 z 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 z 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%0DF)xOoVi=mYKd6t&M~{@@H0N&fr$? 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 C!uYvmd?eIPVuOp7vqvu{lWSN)DOLI8ID+$ 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

#X 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 z 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

2uP$ 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

!6*nAO46!>68H$6&DfqQb866gqCfs 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�%u0fv@Z<+eYd`VdGP!qS_AY(y+_*t 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 IM<|b-b|_d1IsK##Z-@4+}Rw9p2dC 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 z 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

lb_sYsKO-}?YpBqR>)t^LT)WM4!#fDX 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ǰa&_y>ZCm<&r2Wnuy31pS<& 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 F_|dIZb=RUx~rK$I^=g4f%GL^2=7v+ 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 z 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
(Hxbq{uY}jACc(+hyHZSl2 zIh*K|pIzw9!ECNIKdP((e5fii+Cf*h6btw-Z}0s+ww)RbmcrnFn;FbMsQ6`x9RV>F*`n3tz#JRWrrSefgWdED07V-yYrDE_+~MytK=@Nra)i$b=`btkjS=zL`C z1N+*Dft_%E0`*!+I<`&7IG6`oGOL23BzN!_MuPtUGj6PVl)EO{4D^f#3|U5tTPMO` zXwXvI2dvL{E#6cT)xRR#av*gOmv*+p61sY??}8@joUS79Z3u&C_V;u!GPfE*c!8cq z&~4uOiGRJnr(1VhzoqG+^D1gv z-q6auv_Ej9XhUudvr~L_sWpVQzuh;FUpIcFaS$o=b#U-&KzziB_-D>uIqD(H=Xi6e zbcE@QC%v6CmFr)W5uGkrN7m=XsK@p!qV|qCTlXF0q?=~%EVljm_i##wtz~gTWK{IU z(wqe#aLQ|v8)Z_=M`e43^$`1Dt&R%jM354|%|n3uZG#%9cl=oIF8Y^rKNuCfuVnMb zC?*jg3qG9hk)chfM_wDd$Fv2{fKGOYbJk1I9oWs%|FtcuwuU$ zpq+}h8rQ>k9f;?3h0@M8>&uuNMEU+%=D;ayIeFjY%xLG6fBU&NC~ZO&p;JP<@*0#1 z1SSE0p&Tlw+NA5iR~l!K8XMt#;cg(=G(t^JUsd}_{?AIJ2Gm;=svnJxNekfqYFj-p z`|c&s_`C1ZzkVnltCIFBzQlq1WTNIazd-%?U>n=uTRQovr|mfqUKXywNA578trNO^ z!yLLRg4OFJ*as1T5e}Mnekp_Bw{%xQ%7-%V^M5SSR)75+mUAFV?G3ncmlDHv*maTl z=Rx%+2`PZObIPa1v(HDda*Sa-XJISS6^WOm9~>~#gsmw(HC~;$Qjm8kV%ui%G=uBk z&&D&sb)UuG3PqolyDt6X_;!nvu29c>u~)0v+M0%^zlsIt^<>%3{+$DlD{ml8TQJJBNkl7y3oRUY}>AZqNSGukgEbi zy@;4W#0yhgiD}o@vZQ{<3yws!D18_@2I7M1x;U<`&9_D;g{ zWVD5i7!lZ)XASyXnUkPA*$QkT4B;!^V)|6>OY%j_-Xap$VJK-wn<0n+jF_npCzNm~ zFlgvNS40bnfX1lJriJ4y#AXB7osAXMw;&p|DqHZ6p|n|?o?AV^SQ2{Kk@3Lpg;Z|- z?lLIkl}NK>-=Cwq>GzI&?=1YVW9{RIkKUoASdP z+T8|4{eioyT>4C*QNu+dHp^`lNV9{qnW_mA=}9StGOi_1iy!ffAb##41TL3?pTQj* zf_#z~GeNHwd~>%>8a!n-vlPfod%*>AP zM>G%)>lo4;Ut>&niH^$oc`^*%BBY>Yzk-Zd!XL4)<@V=RJB4Ly3|5_j2w>C8Nts$G zQ4nuUT$2~$!#BZ*|qTk|V{8UsXg@0tWq5Vo06D3&VYzh;vEKVA7 z%E}udC8OEJ>Eqw#!rq2Rj5Lti152jvkTl*mB{^Z^2>q2_r0PKva@nX(VYIg>DF`4Y zlOpMT>z=D~PR?-6{-N)Ny?Zn>@|gWyT-iGq zIu<>EqUw0rP-8$;HqvP26&#iLJVfafSKQJOoJzka*GS^4D>_T_y&63*Ss462hD=CP zy{Iq>g%0%{Wsdyztm+Sjmsm*g;k!rccRNb-~ecd*+uzri%5a zqK`S$KGfffNvz9lZgRKWnR#D`qY<<<{VY1U=v0eMNVK)5^)E3inj!cYl9DFbEdyZJ zjx_X@oSnQ6-nH;Fo;=D@*g-=i(>e# zG!{nQ?_PF@6)>a@9^=DcW6e;24x5e{rDTIklX FaW_V}^#b5rgFYPM$4SB*U}iJw}t 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 |_B5G+Z$Ry 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 literal 0 HcmV?d00001 diff --git a/PyTorch/NLP/new-Transformer/docs/getting_started.rst b/PyTorch/NLP/new-Transformer/docs/getting_started.rst new file mode 100644 index 00000000..745ad776 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/getting_started.rst @@ -0,0 +1,216 @@ +Evaluating Pre-trained Models +============================= + +First, download a pre-trained model along with its vocabularies: + +.. code-block:: console + + > curl https://dl.fbaipublicfiles.com/fairseq/models/wmt14.v2.en-fr.fconv-py.tar.bz2 | tar xvjf - + +This model uses a `Byte Pair Encoding (BPE) +vocabulary `__, so we'll have to apply +the encoding to the source text before it can be translated. This can be +done with the +`apply\_bpe.py `__ +script using the ``wmt14.en-fr.fconv-cuda/bpecodes`` file. ``@@`` is +used as a continuation marker and the original text can be easily +recovered with e.g. ``sed s/@@ //g`` or by passing the ``--remove-bpe`` +flag to :ref:`fairseq-generate`. Prior to BPE, input text needs to be tokenized +using ``tokenizer.perl`` from +`mosesdecoder `__. + +Let's use :ref:`fairseq-interactive` to generate translations interactively. +Here, we use a beam size of 5 and preprocess the input with the Moses +tokenizer and the given Byte-Pair Encoding vocabulary. It will automatically +remove the BPE continuation markers and detokenize the output. + +.. code-block:: console + + > MODEL_DIR=wmt14.en-fr.fconv-py + > fairseq-interactive \ + --path $MODEL_DIR/model.pt $MODEL_DIR \ + --beam 5 --source-lang en --target-lang fr \ + --tokenizer moses \ + --bpe subword_nmt --bpe-codes $MODEL_DIR/bpecodes + | loading model(s) from wmt14.en-fr.fconv-py/model.pt + | [en] dictionary: 44206 types + | [fr] dictionary: 44463 types + | Type the input sentence and press return: + Why is it rare to discover new marine mammal species? + S-0 Why is it rare to discover new marine mam@@ mal species ? + H-0 -0.0643349438905716 Pourquoi est-il rare de découvrir de nouvelles espèces de mammifères marins? + P-0 -0.0763 -0.1849 -0.0956 -0.0946 -0.0735 -0.1150 -0.1301 -0.0042 -0.0321 -0.0171 -0.0052 -0.0062 -0.0015 + +This generation script produces three types of outputs: a line prefixed +with *O* is a copy of the original source sentence; *H* is the +hypothesis along with an average log-likelihood; and *P* is the +positional score per token position, including the +end-of-sentence marker which is omitted from the text. + +Other types of output lines you might see are *D*, the detokenized hypothesis, +*T*, the reference target, *A*, alignment info, *E* the history of generation steps. + +See the `README `__ for a +full list of pre-trained models available. + +Training a New Model +==================== + +The following tutorial is for machine translation. For an example of how +to use Fairseq for other tasks, such as :ref:`language modeling`, please see the +``examples/`` directory. + +Data Pre-processing +------------------- + +Fairseq contains example pre-processing scripts for several translation +datasets: IWSLT 2014 (German-English), WMT 2014 (English-French) and WMT +2014 (English-German). To pre-process and binarize the IWSLT dataset: + +.. code-block:: console + + > cd examples/translation/ + > bash prepare-iwslt14.sh + > cd ../.. + > TEXT=examples/translation/iwslt14.tokenized.de-en + > fairseq-preprocess --source-lang de --target-lang en \ + --trainpref $TEXT/train --validpref $TEXT/valid --testpref $TEXT/test \ + --destdir data-bin/iwslt14.tokenized.de-en + +This will write binarized data that can be used for model training to +``data-bin/iwslt14.tokenized.de-en``. + +Training +-------- + +Use :ref:`fairseq-train` to train a new model. Here a few example settings that work +well for the IWSLT 2014 dataset: + +.. code-block:: console + + > mkdir -p checkpoints/fconv + > CUDA_VISIBLE_DEVICES=0 fairseq-train data-bin/iwslt14.tokenized.de-en \ + --optimizer nag --lr 0.25 --clip-norm 0.1 --dropout 0.2 --max-tokens 4000 \ + --arch fconv_iwslt_de_en --save-dir checkpoints/fconv + +By default, :ref:`fairseq-train` will use all available GPUs on your machine. Use the +``CUDA_VISIBLE_DEVICES`` environment variable to select specific GPUs and/or to +change the number of GPU devices that will be used. + +Also note that the batch size is specified in terms of the maximum +number of tokens per batch (``--max-tokens``). You may need to use a +smaller value depending on the available GPU memory on your system. + +Generation +---------- + +Once your model is trained, you can generate translations using +:ref:`fairseq-generate` **(for binarized data)** or +:ref:`fairseq-interactive` **(for raw text)**: + +.. code-block:: console + + > fairseq-generate data-bin/iwslt14.tokenized.de-en \ + --path checkpoints/fconv/checkpoint_best.pt \ + --batch-size 128 --beam 5 + | [de] dictionary: 35475 types + | [en] dictionary: 24739 types + | data-bin/iwslt14.tokenized.de-en test 6750 examples + | model fconv + | loaded checkpoint trainings/fconv/checkpoint_best.pt + S-721 danke . + T-721 thank you . + ... + +To generate translations with only a CPU, use the ``--cpu`` flag. BPE +continuation markers can be removed with the ``--remove-bpe`` flag. + +Advanced Training Options +========================= + +Large mini-batch training with delayed updates +---------------------------------------------- + +The ``--update-freq`` option can be used to accumulate gradients from +multiple mini-batches and delay updating, creating a larger effective +batch size. Delayed updates can also improve training speed by reducing +inter-GPU communication costs and by saving idle time caused by variance +in workload across GPUs. See `Ott et al. +(2018) `__ for more details. + +To train on a single GPU with an effective batch size that is equivalent +to training on 8 GPUs: + +.. code-block:: console + + > CUDA_VISIBLE_DEVICES=0 fairseq-train --update-freq 8 (...) + +Training with half precision floating point (FP16) +-------------------------------------------------- + +.. note:: + + FP16 training requires a Volta GPU and CUDA 9.1 or greater + +Recent GPUs enable efficient half precision floating point computation, +e.g., using `Nvidia Tensor Cores +`__. +Fairseq supports FP16 training with the ``--fp16`` flag: + +.. code-block:: console + + > fairseq-train --fp16 (...) + +Distributed training +-------------------- + +Distributed training in fairseq is implemented on top of ``torch.distributed``. +The easiest way to launch jobs is with the `torch.distributed.launch +`__ tool. + +For example, to train a large English-German Transformer model on 2 nodes each +with 8 GPUs (in total 16 GPUs), run the following command on each node, +replacing ``node_rank=0`` with ``node_rank=1`` on the second node and making +sure to update ``--master_addr`` to the IP address of the first node: + +.. code-block:: console + + > python -m torch.distributed.launch --nproc_per_node=8 \ + --nnodes=2 --node_rank=0 --master_addr="192.168.1.1" \ + --master_port=12345 \ + $(which fairseq-train) data-bin/wmt16_en_de_bpe32k \ + --arch transformer_vaswani_wmt_en_de_big --share-all-embeddings \ + --optimizer adam --adam-betas '(0.9, 0.98)' --clip-norm 0.0 \ + --lr-scheduler inverse_sqrt --warmup-init-lr 1e-07 --warmup-updates 4000 \ + --lr 0.0005 \ + --dropout 0.3 --weight-decay 0.0 --criterion label_smoothed_cross_entropy --label-smoothing 0.1 \ + --max-tokens 3584 \ + --max-epoch 70 \ + --fp16 + +On SLURM clusters, fairseq will automatically detect the number of nodes and +GPUs, but a port number must be provided: + +.. code-block:: console + + > salloc --gpus=16 --nodes 2 (...) + > srun fairseq-train --distributed-port 12345 (...). + +Sharding very large datasets +---------------------------- + +It can be challenging to train over very large datasets, particularly if your +machine does not have much system RAM. Most tasks in fairseq support training +over "sharded" datasets, in which the original dataset has been preprocessed +into non-overlapping chunks (or "shards"). + +For example, instead of preprocessing all your data into a single "data-bin" +directory, you can split the data and create "data-bin1", "data-bin2", etc. +Then you can adapt your training command like so: + +.. code-block:: console + + > fairseq-train data-bin1:data-bin2:data-bin3 (...) + +Training will now iterate over each shard, one by one, with each shard +corresponding to an "epoch", thus reducing system memory usage. diff --git a/PyTorch/NLP/new-Transformer/docs/hydra_integration.md b/PyTorch/NLP/new-Transformer/docs/hydra_integration.md new file mode 100644 index 00000000..6a152983 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/hydra_integration.md @@ -0,0 +1,284 @@ +## Hydra + +[Hydra](https://github.com/facebookresearch/hydra) is an open-source Python +framework that simplifies the development of research and other complex +applications. The key feature is the ability to dynamically create a +hierarchical configuration by composition and override it through config files +and the command line. The name Hydra comes from its ability to run multiple +similar jobs - much like a Hydra with multiple heads. + +## Motivation + +Until recently, all components in fairseq were configured through a shared +`args` namespace that was created at application startup. Components declared +their own `add_args` method to update the argparse parser, hoping that the names +would not clash with arguments from other components. While this model works for +smaller applications, as fairseq grew and became integrated into other +applications, this became problematic. In order to determine how to configure +each component, one needed to a) examine what args were added by this component, +and b) read the code to figure out what shared arguments it is using that were +added in other places. Reproducing models involved sharing commands that often +contained dozens of command line switches. + +The model described above is still supported by fairseq for backward +compatibility, but will be deprecated some time in the future. + +New components in fairseq should now create a dataclass that encapsulates all +parameters required to configure this component. The dataclass is registered +along with the component, and fairseq takes care of constructing and providing +this configuration object to the component's constructor. Note that sharing +parameters can optionally still work, but one has to explicitly point to the +"source of truth" (see inheritance example below). These changes make components +in fairseq more independent and re-usable by other applications: all that is +needed to create a component is to initialize its dataclass and overwrite some +of the defaults. + +While configuring fairseq through command line (using either the legacy argparse +based or the new Hydra based entry points) is still fully supported, you can now +take advantage of configuring fairseq completely or piece-by-piece through +hierarchical YAML configuration files. These files can also be shipped as +examples that others can use to run an identically configured job. + +Additionally, Hydra has a rich and growing [library of +plugins](https://github.com/facebookresearch/hydra/tree/master/plugins) that +provide functionality such as hyperparameter sweeping (including using bayesian +optimization through the [Ax](https://github.com/facebook/Ax) library), job +launching across various platforms, and more. + +## Creating or migrating components + +In general, each new (or updated) component should provide a companion +[dataclass](https://www.python.org/dev/peps/pep-0557/). These dataclass are +typically located in the same file as the component and are passed as arguments +to the `register_*()` functions. Top-level configs that should be present in +every fairseq application are placed in the +[global](fairseq/dataclass/configs.py) config file and added to the +`FairseqConfig` object. + +Each dataclass is a plain-old-data object, similar to a `NamedTuple`. These +classes are decorated with a `@dataclass` decorator, and typically inherit from +`FairseqDataclass` (which adds some functionality for backward compatibility). +Each field must have a type, and generally has metadata (such as a help string) +and a default value. Only primitive types or other config objects are allowed as +data types for each field. + +#### Example: + +```python +from dataclasses import dataclass, field +from fairseq.dataclass import FairseqDataclass + +@dataclass +class InteractiveConfig(FairseqDataclass): + buffer_size: int = field( + default=0, + metadata={ + "help": "read this many sentences into a buffer before processing them" + }, + ) + input: str = field( + default="-", + metadata={"help": "file to read from; use - for stdin"}, + ) +``` + +### Inherting values + +Some components require sharing a value. For example, a learning rate scheduler +and an optimizer may both need to know the initial learning rate value. One can +declare a field that, by default, will inherit its value from another config +node in the same hierarchy: + +```python +@dataclass +FairseqAdamConfig(FairseqDataclass): + ... + lr: List[float] = II("optimization.lr") + ... +``` + +`II("optimization.lr")` is syntactic sugar for `"${optimization.lr}"`, which is +the value one can use in a YAML config file or through command line to achieve +the same effect. Note that this assumes that there is an "optimization" config +object in the root config and it has a field called "lr". + +### Tasks and Models + +Creating Tasks and Models works same as before, except that legacy +implementations now inherit from `LegacyFairseq*` base classes, while new +components inherit from `FairseqTask` and `FairseqModel` and provide a dataclass +to the `register_*()` functions. + +#### Task example: + +```python +@dataclass +class LanguageModelingConfig(FairseqDataclass): + data: Optional[str] = field( + default=None, metadata={"help": "path to data directory"} + ) + ... + +@register_task("language_modeling", dataclass=LanguageModelingConfig) +class LanguageModelingTask(FairseqTask): + ... + @classmethod + def setup_task(cls, cfg: LanguageModelingConfig): + ... +``` + +#### Model example: + +```python +@dataclass +class TransformerLanguageModelConfig(FairseqDataclass): + activation_fn: ChoiceEnum(utils.get_available_activation_fns()) = field( + default="relu", metadata={"help": "activation function to use"} + ) + dropout: float = field(default=0.1, metadata={"help": "dropout probability"}) + ... + +@register_model("transformer_lm", dataclass=TransformerLanguageModelConfig) +class TransformerLanguageModel(FairseqLanguageModel): + ... + @classmethod + def build_model(cls, cfg: TransformerLanguageModelConfig, task: FairseqTask): + ... +``` + +### Other components + +Other components work as before, but they now take their configuration dataclass +as the only constructor argument: + +```python +@dataclass +class MosesTokenizerConfig(FairseqDataclass): + source_lang: str = field(default="en", metadata={"help": "source language"}) + ... + +@register_tokenizer("moses", dataclass=MosesTokenizerConfig) +class MosesTokenizer(object): + def __init__(self, cfg: MosesTokenizerConfig): + ... +``` + +Note that if you are adding a new registry for a new set of components, you need +to add it to the `FairseqConfig` object in `fairseq/dataclass/configs.py`: + +```python +@dataclass +class FairseqConfig(object): + ... + my_new_registry: Any = None +``` + +## Training with `fairseq-hydra-train` + +To fully take advantage of configuration flexibility offered by Hydra, you may +want to train new models using the `fairseq-hydra-train` entry point. Legacy CLI +tools such as `fairseq-train` will remain supported for the foreseeable future +but will be deprecated eventually. + +On startup, Hydra will create a configuration object that contains a hierarchy +of all the necessary dataclasses populated with their default values in the +code. The default values are overwritten by values found in YAML files in +`fairseq/config` directory (which currently sets minimal defaults) and then +further overwritten by values provided through command line arguments. + +Some of the most common use cases are shown below: + +### 1. Override default values through command line: + +```shell script +$ fairseq-hydra-train \ + distributed_training.distributed_world_size=1 \ + dataset.batch_size=2 \ + task.data=data-bin \ + model=transformer_lm/transformer_lm_gpt \ + task=language_modeling \ + optimization.max_update=5000 +``` + +Note that along with explicitly providing values for parameters such as +`dataset.batch_size`, this also tells Hydra to overlay configuration found in +`fairseq/config/model/transformer_lm/transformer_lm_gpt.yaml` over the default +values in the dataclass. If you want to train a model without specifying a +particular architecture you can simply specify `model=transformer_lm`. This only +works for migrated tasks and models. + +### 2. Replace bundled configs with an external config: + +```shell script +$ fairseq-hydra-train \ + --config-dir /path/to/external/configs \ + --config-name wiki103 +``` + +where `/path/to/external/configs/wiki103.yaml` contains: + +```yaml +# @package _group_ + +model: + _name: transformer_lm +distributed_training: + distributed_world_size: 1 +dataset: + batch_size: 2 +task: + _name: language_modeling + data: /path/to/data + add_bos_token: false + max_target_positions: 1024 +optimization: + max_update: 50000 + lr: [ 0.25 ] +criterion: cross_entropy +optimizer: adam +lr_scheduler: + _name: cosine +``` + +Note that here bundled configs from `fairseq/config` directory are not used, +however the defaults from each dataclass will still be used (unless overwritten +by your external config). + +Additionally you can choose to break up your configs by creating a directory +structure in the same location as your main config file, with the names of the +top-level fields (such as "model", "dataset", etc), and placing config files +with meaningful names that would populate that specific section of your +top-level config file (for example, you might have +`model/small_transformer_lm.yaml`, `model/big_transformer_lm.yaml`, etc). You +can then specify the correct configuration via command line, defaults in the +main config, or even launch all of them as a sweep (see Hydra documentation on +how to do this). + +### 3. Add an external config directory to Hydra search path: + +This allows combining default configuration (including using any bundled config +files), while specifying your own config files for some parts of the +configuration. + +```shell script +$ fairseq-hydra-train \ + distributed_training.distributed_world_size=1 \ + dataset.batch_size=2 \ + task.data=/path/to/data/ \ + model=transformer_lm/2_layers \ + task=language_modeling \ + optimization.max_update=5000 \ + --config-dir /path/to/external/configs +``` + +where `/path/to/external/configs` has the following structure: +``` +. ++-- model +| +-- transformer_lm +| | +-- 2_layers.yaml +``` + +and `2_layers.yaml` contains a copy of `transformer_lm_gpt.yaml` but with +`decoder_layers` set to 2. You can add other configs to configure other +components as well. diff --git a/PyTorch/NLP/new-Transformer/docs/index.rst b/PyTorch/NLP/new-Transformer/docs/index.rst new file mode 100644 index 00000000..591db86c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/index.rst @@ -0,0 +1,49 @@ +.. fairseq documentation master file, created by + sphinx-quickstart on Fri Aug 17 21:45:30 2018. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +:github_url: https://github.com/pytorch/fairseq + + +fairseq documentation +===================== + +Fairseq is a sequence modeling toolkit written in `PyTorch +`_ that allows researchers and developers to +train custom models for translation, summarization, language modeling and other +text generation tasks. + +.. toctree:: + :maxdepth: 1 + :caption: Getting Started + + getting_started + command_line_tools + +.. toctree:: + :maxdepth: 1 + :caption: Extending Fairseq + + overview + tutorial_simple_lstm + tutorial_classifying_names + +.. toctree:: + :maxdepth: 2 + :caption: Library Reference + + tasks + models + criterions + optim + lr_scheduler + data + modules + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` diff --git a/PyTorch/NLP/new-Transformer/docs/lr_scheduler.rst b/PyTorch/NLP/new-Transformer/docs/lr_scheduler.rst new file mode 100644 index 00000000..bbc09dc2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/lr_scheduler.rst @@ -0,0 +1,34 @@ +.. role:: hidden + :class: hidden-section + +.. _Learning Rate Schedulers: + +Learning Rate Schedulers +======================== + +Learning Rate Schedulers update the learning rate over the course of training. +Learning rates can be updated after each update via :func:`step_update` or at +epoch boundaries via :func:`step`. + +.. automodule:: fairseq.optim.lr_scheduler + :members: + +.. autoclass:: fairseq.optim.lr_scheduler.FairseqLRScheduler + :members: + :undoc-members: + +.. autoclass:: fairseq.optim.lr_scheduler.cosine_lr_scheduler.CosineSchedule + :members: + :undoc-members: +.. autoclass:: fairseq.optim.lr_scheduler.fixed_schedule.FixedSchedule + :members: + :undoc-members: +.. autoclass:: fairseq.optim.lr_scheduler.inverse_square_root_schedule.InverseSquareRootSchedule + :members: + :undoc-members: +.. autoclass:: fairseq.optim.lr_scheduler.reduce_lr_on_plateau.ReduceLROnPlateau + :members: + :undoc-members: +.. autoclass:: fairseq.optim.lr_scheduler.triangular_lr_scheduler.TriangularSchedule + :members: + :undoc-members: diff --git a/PyTorch/NLP/new-Transformer/docs/make.bat b/PyTorch/NLP/new-Transformer/docs/make.bat new file mode 100644 index 00000000..baa9d02a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/make.bat @@ -0,0 +1,36 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=python -msphinx +) +set SOURCEDIR=. +set BUILDDIR=_build +set SPHINXPROJ=fairseq + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The Sphinx module was not found. Make sure you have Sphinx installed, + echo.then set the SPHINXBUILD environment variable to point to the full + echo.path of the 'sphinx-build' executable. Alternatively you may add the + echo.Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% + +:end +popd diff --git a/PyTorch/NLP/new-Transformer/docs/models.rst b/PyTorch/NLP/new-Transformer/docs/models.rst new file mode 100644 index 00000000..054622d5 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/models.rst @@ -0,0 +1,104 @@ +.. role:: hidden + :class: hidden-section + +.. module:: fairseq.models + +.. _Models: + +Models +====== + +A Model defines the neural network's ``forward()`` method and encapsulates all +of the learnable parameters in the network. Each model also provides a set of +named *architectures* that define the precise network configuration (e.g., +embedding dimension, number of layers, etc.). + +Both the model type and architecture are selected via the ``--arch`` +command-line argument. Once selected, a model may expose additional command-line +arguments for further configuration. + +.. note:: + + All fairseq Models extend :class:`BaseFairseqModel`, which in turn extends + :class:`torch.nn.Module`. Thus any fairseq Model can be used as a + stand-alone Module in other PyTorch code. + + +Convolutional Neural Networks (CNN) +----------------------------------- + +.. module:: fairseq.models.fconv +.. autoclass:: fairseq.models.fconv.FConvModel + :members: +.. autoclass:: fairseq.models.fconv.FConvEncoder + :members: + :undoc-members: +.. autoclass:: fairseq.models.fconv.FConvDecoder + :members: + + +Long Short-Term Memory (LSTM) networks +-------------------------------------- + +.. module:: fairseq.models.lstm +.. autoclass:: fairseq.models.lstm.LSTMModel + :members: +.. autoclass:: fairseq.models.lstm.LSTMEncoder + :members: +.. autoclass:: fairseq.models.lstm.LSTMDecoder + :members: + + +Transformer (self-attention) networks +------------------------------------- + +.. module:: fairseq.models.transformer +.. autoclass:: fairseq.models.transformer.TransformerModel + :members: +.. autoclass:: fairseq.models.transformer.TransformerEncoder + :members: +.. autoclass:: fairseq.models.transformer.TransformerEncoderLayer + :members: +.. autoclass:: fairseq.models.transformer.TransformerDecoder + :members: +.. autoclass:: fairseq.models.transformer.TransformerDecoderLayer + :members: + + +Adding new models +----------------- + +.. currentmodule:: fairseq.models +.. autofunction:: fairseq.models.register_model +.. autofunction:: fairseq.models.register_model_architecture +.. autoclass:: fairseq.models.BaseFairseqModel + :members: + :undoc-members: +.. autoclass:: fairseq.models.FairseqEncoderDecoderModel + :members: + :undoc-members: +.. autoclass:: fairseq.models.FairseqEncoderModel + :members: + :undoc-members: +.. autoclass:: fairseq.models.FairseqLanguageModel + :members: + :undoc-members: +.. autoclass:: fairseq.models.FairseqMultiModel + :members: + :undoc-members: +.. autoclass:: fairseq.models.FairseqEncoder + :members: +.. autoclass:: fairseq.models.CompositeEncoder + :members: +.. autoclass:: fairseq.models.FairseqDecoder + :members: + + +.. _Incremental decoding: + +Incremental decoding +-------------------- + +.. autoclass:: fairseq.models.FairseqIncrementalDecoder + :members: + :undoc-members: diff --git a/PyTorch/NLP/new-Transformer/docs/modules.rst b/PyTorch/NLP/new-Transformer/docs/modules.rst new file mode 100644 index 00000000..9631c93d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/modules.rst @@ -0,0 +1,9 @@ +Modules +======= + +Fairseq provides several stand-alone :class:`torch.nn.Module` classes that may +be helpful when implementing a new :class:`~fairseq.models.BaseFairseqModel`. + +.. automodule:: fairseq.modules + :members: + :undoc-members: diff --git a/PyTorch/NLP/new-Transformer/docs/optim.rst b/PyTorch/NLP/new-Transformer/docs/optim.rst new file mode 100644 index 00000000..c3326456 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/optim.rst @@ -0,0 +1,38 @@ +.. role:: hidden + :class: hidden-section + +.. _optimizers: + +Optimizers +========== + +Optimizers update the Model parameters based on the gradients. + +.. automodule:: fairseq.optim + :members: + +.. autoclass:: fairseq.optim.FairseqOptimizer + :members: + :undoc-members: + +.. autoclass:: fairseq.optim.adadelta.Adadelta + :members: + :undoc-members: +.. autoclass:: fairseq.optim.adagrad.Adagrad + :members: + :undoc-members: +.. autoclass:: fairseq.optim.adafactor.FairseqAdafactor + :members: + :undoc-members: +.. autoclass:: fairseq.optim.adam.FairseqAdam + :members: + :undoc-members: +.. autoclass:: fairseq.optim.fp16_optimizer.FP16Optimizer + :members: + :undoc-members: +.. autoclass:: fairseq.optim.nag.FairseqNAG + :members: + :undoc-members: +.. autoclass:: fairseq.optim.sgd.SGD + :members: + :undoc-members: diff --git a/PyTorch/NLP/new-Transformer/docs/overview.rst b/PyTorch/NLP/new-Transformer/docs/overview.rst new file mode 100644 index 00000000..026b3b5c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/overview.rst @@ -0,0 +1,74 @@ +Overview +======== + +Fairseq can be extended through user-supplied `plug-ins +`_. We support five kinds of +plug-ins: + +- :ref:`Models` define the neural network architecture and encapsulate all of the + learnable parameters. +- :ref:`Criterions` compute the loss function given the model outputs and targets. +- :ref:`Tasks` store dictionaries and provide helpers for loading/iterating over + Datasets, initializing the Model/Criterion and calculating the loss. +- :ref:`Optimizers` update the Model parameters based on the gradients. +- :ref:`Learning Rate Schedulers` update the learning rate over the course of + training. + +**Training Flow** + +Given a ``model``, ``criterion``, ``task``, ``optimizer`` and ``lr_scheduler``, +fairseq implements the following high-level training flow:: + + for epoch in range(num_epochs): + itr = task.get_batch_iterator(task.dataset('train')) + for num_updates, batch in enumerate(itr): + task.train_step(batch, model, criterion, optimizer) + average_and_clip_gradients() + optimizer.step() + lr_scheduler.step_update(num_updates) + lr_scheduler.step(epoch) + +where the default implementation for ``task.train_step`` is roughly:: + + def train_step(self, batch, model, criterion, optimizer, **unused): + loss = criterion(model, batch) + optimizer.backward(loss) + return loss + +**Registering new plug-ins** + +New plug-ins are *registered* through a set of ``@register`` function +decorators, for example:: + + @register_model('my_lstm') + class MyLSTM(FairseqEncoderDecoderModel): + (...) + +Once registered, new plug-ins can be used with the existing :ref:`Command-line +Tools`. See the Tutorial sections for more detailed walkthroughs of how to add +new plug-ins. + +**Loading plug-ins from another directory** + +New plug-ins can be defined in a custom module stored in the user system. In +order to import the module, and make the plugin available to *fairseq*, the +command line supports the ``--user-dir`` flag that can be used to specify a +custom location for additional modules to load into *fairseq*. + +For example, assuming this directory tree:: + + /home/user/my-module/ + └── __init__.py + +with ``__init__.py``:: + + from fairseq.models import register_model_architecture + from fairseq.models.transformer import transformer_vaswani_wmt_en_de_big + + @register_model_architecture('transformer', 'my_transformer') + def transformer_mmt_big(args): + transformer_vaswani_wmt_en_de_big(args) + +it is possible to invoke the :ref:`fairseq-train` script with the new architecture with:: + + fairseq-train ... --user-dir /home/user/my-module -a my_transformer --task translation diff --git a/PyTorch/NLP/new-Transformer/docs/requirements.txt b/PyTorch/NLP/new-Transformer/docs/requirements.txt new file mode 100644 index 00000000..c734a1f0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/requirements.txt @@ -0,0 +1,2 @@ +sphinx<2.0 +sphinx-argparse diff --git a/PyTorch/NLP/new-Transformer/docs/tasks.rst b/PyTorch/NLP/new-Transformer/docs/tasks.rst new file mode 100644 index 00000000..5f65c3c8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/tasks.rst @@ -0,0 +1,61 @@ +.. role:: hidden + :class: hidden-section + +.. module:: fairseq.tasks + +.. _Tasks: + +Tasks +===== + +Tasks store dictionaries and provide helpers for loading/iterating over +Datasets, initializing the Model/Criterion and calculating the loss. + +Tasks can be selected via the ``--task`` command-line argument. Once selected, a +task may expose additional command-line arguments for further configuration. + +Example usage:: + + # setup the task (e.g., load dictionaries) + task = fairseq.tasks.setup_task(args) + + # build model and criterion + model = task.build_model(args) + criterion = task.build_criterion(args) + + # load datasets + task.load_dataset('train') + task.load_dataset('valid') + + # iterate over mini-batches of data + batch_itr = task.get_batch_iterator( + task.dataset('train'), max_tokens=4096, + ) + for batch in batch_itr: + # compute the loss + loss, sample_size, logging_output = task.get_loss( + model, criterion, batch, + ) + loss.backward() + + +Translation +----------- + +.. autoclass:: fairseq.tasks.translation.TranslationTask + +.. _language modeling: + +Language Modeling +----------------- + +.. autoclass:: fairseq.tasks.language_modeling.LanguageModelingTask + + +Adding new tasks +---------------- + +.. autofunction:: fairseq.tasks.register_task +.. autoclass:: fairseq.tasks.FairseqTask + :members: + :undoc-members: diff --git a/PyTorch/NLP/new-Transformer/docs/tutorial_classifying_names.rst b/PyTorch/NLP/new-Transformer/docs/tutorial_classifying_names.rst new file mode 100644 index 00000000..b02fec04 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/tutorial_classifying_names.rst @@ -0,0 +1,415 @@ +Tutorial: Classifying Names with a Character-Level RNN +====================================================== + +In this tutorial we will extend fairseq to support *classification* tasks. In +particular we will re-implement the PyTorch tutorial for `Classifying Names with +a Character-Level RNN `_ +in fairseq. It is recommended to quickly skim that tutorial before beginning +this one. + +This tutorial covers: + +1. **Preprocessing the data** to create dictionaries. +2. **Registering a new Model** that encodes an input sentence with a simple RNN + and predicts the output label. +3. **Registering a new Task** that loads our dictionaries and dataset. +4. **Training the Model** using the existing command-line tools. +5. **Writing an evaluation script** that imports fairseq and allows us to + interactively evaluate our model on new inputs. + + +1. Preprocessing the data +------------------------- + +The original tutorial provides raw data, but we'll work with a modified version +of the data that is already tokenized into characters and split into separate +train, valid and test sets. + +Download and extract the data from here: +`tutorial_names.tar.gz `_ + +Once extracted, let's preprocess the data using the :ref:`fairseq-preprocess` +command-line tool to create the dictionaries. While this tool is primarily +intended for sequence-to-sequence problems, we're able to reuse it here by +treating the label as a "target" sequence of length 1. We'll also output the +preprocessed files in "raw" format using the ``--dataset-impl`` option to +enhance readability: + +.. code-block:: console + + > fairseq-preprocess \ + --trainpref names/train --validpref names/valid --testpref names/test \ + --source-lang input --target-lang label \ + --destdir names-bin --dataset-impl raw + +After running the above command you should see a new directory, +:file:`names-bin/`, containing the dictionaries for *inputs* and *labels*. + + +2. Registering a new Model +-------------------------- + +Next we'll register a new model in fairseq that will encode an input sentence +with a simple RNN and predict the output label. Compared to the original PyTorch +tutorial, our version will also work with batches of data and GPU Tensors. + +First let's copy the simple RNN module implemented in the `PyTorch tutorial +`_. +Create a new file named :file:`fairseq/models/rnn_classifier.py` with the +following contents:: + + import torch + import torch.nn as nn + + class RNN(nn.Module): + + def __init__(self, input_size, hidden_size, output_size): + super(RNN, self).__init__() + + self.hidden_size = hidden_size + + self.i2h = nn.Linear(input_size + hidden_size, hidden_size) + self.i2o = nn.Linear(input_size + hidden_size, output_size) + self.softmax = nn.LogSoftmax(dim=1) + + def forward(self, input, hidden): + combined = torch.cat((input, hidden), 1) + hidden = self.i2h(combined) + output = self.i2o(combined) + output = self.softmax(output) + return output, hidden + + def initHidden(self): + return torch.zeros(1, self.hidden_size) + +We must also *register* this model with fairseq using the +:func:`~fairseq.models.register_model` function decorator. Once the model is +registered we'll be able to use it with the existing :ref:`Command-line Tools`. + +All registered models must implement the :class:`~fairseq.models.BaseFairseqModel` +interface, so we'll create a small wrapper class in the same file and register +it in fairseq with the name ``'rnn_classifier'``:: + + from fairseq.models import BaseFairseqModel, register_model + + # Note: the register_model "decorator" should immediately precede the + # definition of the Model class. + + @register_model('rnn_classifier') + class FairseqRNNClassifier(BaseFairseqModel): + + @staticmethod + def add_args(parser): + # Models can override this method to add new command-line arguments. + # Here we'll add a new command-line argument to configure the + # dimensionality of the hidden state. + parser.add_argument( + '--hidden-dim', type=int, metavar='N', + help='dimensionality of the hidden state', + ) + + @classmethod + def build_model(cls, args, task): + # Fairseq initializes models by calling the ``build_model()`` + # function. This provides more flexibility, since the returned model + # instance can be of a different type than the one that was called. + # In this case we'll just return a FairseqRNNClassifier instance. + + # Initialize our RNN module + rnn = RNN( + # We'll define the Task in the next section, but for now just + # notice that the task holds the dictionaries for the "source" + # (i.e., the input sentence) and "target" (i.e., the label). + input_size=len(task.source_dictionary), + hidden_size=args.hidden_dim, + output_size=len(task.target_dictionary), + ) + + # Return the wrapped version of the module + return FairseqRNNClassifier( + rnn=rnn, + input_vocab=task.source_dictionary, + ) + + def __init__(self, rnn, input_vocab): + super(FairseqRNNClassifier, self).__init__() + + self.rnn = rnn + self.input_vocab = input_vocab + + # The RNN module in the tutorial expects one-hot inputs, so we can + # precompute the identity matrix to help convert from indices to + # one-hot vectors. We register it as a buffer so that it is moved to + # the GPU when ``cuda()`` is called. + self.register_buffer('one_hot_inputs', torch.eye(len(input_vocab))) + + def forward(self, src_tokens, src_lengths): + # The inputs to the ``forward()`` function are determined by the + # Task, and in particular the ``'net_input'`` key in each + # mini-batch. We'll define the Task in the next section, but for + # now just know that *src_tokens* has shape `(batch, src_len)` and + # *src_lengths* has shape `(batch)`. + bsz, max_src_len = src_tokens.size() + + # Initialize the RNN hidden state. Compared to the original PyTorch + # tutorial we'll also handle batched inputs and work on the GPU. + hidden = self.rnn.initHidden() + hidden = hidden.repeat(bsz, 1) # expand for batched inputs + hidden = hidden.to(src_tokens.device) # move to GPU + + for i in range(max_src_len): + # WARNING: The inputs have padding, so we should mask those + # elements here so that padding doesn't affect the results. + # This is left as an exercise for the reader. The padding symbol + # is given by ``self.input_vocab.pad()`` and the unpadded length + # of each input is given by *src_lengths*. + + # One-hot encode a batch of input characters. + input = self.one_hot_inputs[src_tokens[:, i].long()] + + # Feed the input to our RNN. + output, hidden = self.rnn(input, hidden) + + # Return the final output state for making a prediction + return output + +Finally let's define a *named architecture* with the configuration for our +model. This is done with the :func:`~fairseq.models.register_model_architecture` +function decorator. Thereafter this named architecture can be used with the +``--arch`` command-line argument, e.g., ``--arch pytorch_tutorial_rnn``:: + + from fairseq.models import register_model_architecture + + # The first argument to ``register_model_architecture()`` should be the name + # of the model we registered above (i.e., 'rnn_classifier'). The function we + # register here should take a single argument *args* and modify it in-place + # to match the desired architecture. + + @register_model_architecture('rnn_classifier', 'pytorch_tutorial_rnn') + def pytorch_tutorial_rnn(args): + # We use ``getattr()`` to prioritize arguments that are explicitly given + # on the command-line, so that the defaults defined below are only used + # when no other value has been specified. + args.hidden_dim = getattr(args, 'hidden_dim', 128) + + +3. Registering a new Task +------------------------- + +Now we'll register a new :class:`~fairseq.tasks.FairseqTask` that will load our +dictionaries and dataset. Tasks can also control how the data is batched into +mini-batches, but in this tutorial we'll reuse the batching provided by +:class:`fairseq.data.LanguagePairDataset`. + +Create a new file named :file:`fairseq/tasks/simple_classification.py` with the +following contents:: + + import os + import torch + + from fairseq.data import Dictionary, LanguagePairDataset + from fairseq.tasks import FairseqTask, register_task + + + @register_task('simple_classification') + class SimpleClassificationTask(LegacyFairseqTask): + + @staticmethod + def add_args(parser): + # Add some command-line arguments for specifying where the data is + # located and the maximum supported input length. + parser.add_argument('data', metavar='FILE', + help='file prefix for data') + parser.add_argument('--max-positions', default=1024, type=int, + help='max input length') + + @classmethod + def setup_task(cls, args, **kwargs): + # Here we can perform any setup required for the task. This may include + # loading Dictionaries, initializing shared Embedding layers, etc. + # In this case we'll just load the Dictionaries. + input_vocab = Dictionary.load(os.path.join(args.data, 'dict.input.txt')) + label_vocab = Dictionary.load(os.path.join(args.data, 'dict.label.txt')) + print('| [input] dictionary: {} types'.format(len(input_vocab))) + print('| [label] dictionary: {} types'.format(len(label_vocab))) + + return SimpleClassificationTask(args, input_vocab, label_vocab) + + def __init__(self, args, input_vocab, label_vocab): + super().__init__(args) + self.input_vocab = input_vocab + self.label_vocab = label_vocab + + def load_dataset(self, split, **kwargs): + """Load a given dataset split (e.g., train, valid, test).""" + + prefix = os.path.join(self.args.data, '{}.input-label'.format(split)) + + # Read input sentences. + sentences, lengths = [], [] + with open(prefix + '.input', encoding='utf-8') as file: + for line in file: + sentence = line.strip() + + # Tokenize the sentence, splitting on spaces + tokens = self.input_vocab.encode_line( + sentence, add_if_not_exist=False, + ) + + sentences.append(tokens) + lengths.append(tokens.numel()) + + # Read labels. + labels = [] + with open(prefix + '.label', encoding='utf-8') as file: + for line in file: + label = line.strip() + labels.append( + # Convert label to a numeric ID. + torch.LongTensor([self.label_vocab.add_symbol(label)]) + ) + + assert len(sentences) == len(labels) + print('| {} {} {} examples'.format(self.args.data, split, len(sentences))) + + # We reuse LanguagePairDataset since classification can be modeled as a + # sequence-to-sequence task where the target sequence has length 1. + self.datasets[split] = LanguagePairDataset( + src=sentences, + src_sizes=lengths, + src_dict=self.input_vocab, + tgt=labels, + tgt_sizes=torch.ones(len(labels)), # targets have length 1 + tgt_dict=self.label_vocab, + left_pad_source=False, + # Since our target is a single class label, there's no need for + # teacher forcing. If we set this to ``True`` then our Model's + # ``forward()`` method would receive an additional argument called + # *prev_output_tokens* that would contain a shifted version of the + # target sequence. + input_feeding=False, + ) + + def max_positions(self): + """Return the max input length allowed by the task.""" + # The source should be less than *args.max_positions* and the "target" + # has max length 1. + return (self.args.max_positions, 1) + + @property + def source_dictionary(self): + """Return the source :class:`~fairseq.data.Dictionary`.""" + return self.input_vocab + + @property + def target_dictionary(self): + """Return the target :class:`~fairseq.data.Dictionary`.""" + return self.label_vocab + + # We could override this method if we wanted more control over how batches + # are constructed, but it's not necessary for this tutorial since we can + # reuse the batching provided by LanguagePairDataset. + # + # def get_batch_iterator( + # self, dataset, max_tokens=None, max_sentences=None, max_positions=None, + # ignore_invalid_inputs=False, required_batch_size_multiple=1, + # seed=1, num_shards=1, shard_id=0, num_workers=0, epoch=1, + # data_buffer_size=0, disable_iterator_cache=False, + # ): + # (...) + + +4. Training the Model +--------------------- + +Now we're ready to train the model. We can use the existing :ref:`fairseq-train` +command-line tool for this, making sure to specify our new Task (``--task +simple_classification``) and Model architecture (``--arch +pytorch_tutorial_rnn``): + +.. note:: + + You can also configure the dimensionality of the hidden state by passing the + ``--hidden-dim`` argument to :ref:`fairseq-train`. + +.. code-block:: console + + > fairseq-train names-bin \ + --task simple_classification \ + --arch pytorch_tutorial_rnn \ + --optimizer adam --lr 0.001 --lr-shrink 0.5 \ + --max-tokens 1000 + (...) + | epoch 027 | loss 1.200 | ppl 2.30 | wps 15728 | ups 119.4 | wpb 116 | bsz 116 | num_updates 3726 | lr 1.5625e-05 | gnorm 1.290 | clip 0% | oom 0 | wall 32 | train_wall 21 + | epoch 027 | valid on 'valid' subset | valid_loss 1.41304 | valid_ppl 2.66 | num_updates 3726 | best 1.41208 + | done training in 31.6 seconds + +The model files should appear in the :file:`checkpoints/` directory. + + +5. Writing an evaluation script +------------------------------- + +Finally we can write a short script to evaluate our model on new inputs. Create +a new file named :file:`eval_classifier.py` with the following contents:: + + from fairseq import checkpoint_utils, data, options, tasks + + # Parse command-line arguments for generation + parser = options.get_generation_parser(default_task='simple_classification') + args = options.parse_args_and_arch(parser) + + # Setup task + task = tasks.setup_task(args) + + # Load model + print('| loading model from {}'.format(args.path)) + models, _model_args = checkpoint_utils.load_model_ensemble([args.path], task=task) + model = models[0] + + while True: + sentence = input('\nInput: ') + + # Tokenize into characters + chars = ' '.join(list(sentence.strip())) + tokens = task.source_dictionary.encode_line( + chars, add_if_not_exist=False, + ) + + # Build mini-batch to feed to the model + batch = data.language_pair_dataset.collate( + samples=[{'id': -1, 'source': tokens}], # bsz = 1 + pad_idx=task.source_dictionary.pad(), + eos_idx=task.source_dictionary.eos(), + left_pad_source=False, + input_feeding=False, + ) + + # Feed batch to the model and get predictions + preds = model(**batch['net_input']) + + # Print top 3 predictions and their log-probabilities + top_scores, top_labels = preds[0].topk(k=3) + for score, label_idx in zip(top_scores, top_labels): + label_name = task.target_dictionary.string([label_idx]) + print('({:.2f})\t{}'.format(score, label_name)) + +Now we can evaluate our model interactively. Note that we have included the +original data path (:file:`names-bin/`) so that the dictionaries can be loaded: + +.. code-block:: console + + > python eval_classifier.py names-bin --path checkpoints/checkpoint_best.pt + | [input] dictionary: 64 types + | [label] dictionary: 24 types + | loading model from checkpoints/checkpoint_best.pt + + Input: Satoshi + (-0.61) Japanese + (-1.20) Arabic + (-2.86) Italian + + Input: Sinbad + (-0.30) Arabic + (-1.76) English + (-4.08) Russian diff --git a/PyTorch/NLP/new-Transformer/docs/tutorial_simple_lstm.rst b/PyTorch/NLP/new-Transformer/docs/tutorial_simple_lstm.rst new file mode 100644 index 00000000..f5298850 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/docs/tutorial_simple_lstm.rst @@ -0,0 +1,518 @@ +Tutorial: Simple LSTM +===================== + +In this tutorial we will extend fairseq by adding a new +:class:`~fairseq.models.FairseqEncoderDecoderModel` that encodes a source +sentence with an LSTM and then passes the final hidden state to a second LSTM +that decodes the target sentence (without attention). + +This tutorial covers: + +1. **Writing an Encoder and Decoder** to encode/decode the source/target + sentence, respectively. +2. **Registering a new Model** so that it can be used with the existing + :ref:`Command-line tools`. +3. **Training the Model** using the existing command-line tools. +4. **Making generation faster** by modifying the Decoder to use + :ref:`Incremental decoding`. + + +1. Building an Encoder and Decoder +---------------------------------- + +In this section we'll define a simple LSTM Encoder and Decoder. All Encoders +should implement the :class:`~fairseq.models.FairseqEncoder` interface and +Decoders should implement the :class:`~fairseq.models.FairseqDecoder` interface. +These interfaces themselves extend :class:`torch.nn.Module`, so FairseqEncoders +and FairseqDecoders can be written and used in the same ways as ordinary PyTorch +Modules. + + +Encoder +~~~~~~~ + +Our Encoder will embed the tokens in the source sentence, feed them to a +:class:`torch.nn.LSTM` and return the final hidden state. To create our encoder +save the following in a new file named :file:`fairseq/models/simple_lstm.py`:: + + import torch.nn as nn + from fairseq import utils + from fairseq.models import FairseqEncoder + + class SimpleLSTMEncoder(FairseqEncoder): + + def __init__( + self, args, dictionary, embed_dim=128, hidden_dim=128, dropout=0.1, + ): + super().__init__(dictionary) + self.args = args + + # Our encoder will embed the inputs before feeding them to the LSTM. + self.embed_tokens = nn.Embedding( + num_embeddings=len(dictionary), + embedding_dim=embed_dim, + padding_idx=dictionary.pad(), + ) + self.dropout = nn.Dropout(p=dropout) + + # We'll use a single-layer, unidirectional LSTM for simplicity. + self.lstm = nn.LSTM( + input_size=embed_dim, + hidden_size=hidden_dim, + num_layers=1, + bidirectional=False, + batch_first=True, + ) + + def forward(self, src_tokens, src_lengths): + # The inputs to the ``forward()`` function are determined by the + # Task, and in particular the ``'net_input'`` key in each + # mini-batch. We discuss Tasks in the next tutorial, but for now just + # know that *src_tokens* has shape `(batch, src_len)` and *src_lengths* + # has shape `(batch)`. + + # Note that the source is typically padded on the left. This can be + # configured by adding the `--left-pad-source "False"` command-line + # argument, but here we'll make the Encoder handle either kind of + # padding by converting everything to be right-padded. + if self.args.left_pad_source: + # Convert left-padding to right-padding. + src_tokens = utils.convert_padding_direction( + src_tokens, + padding_idx=self.dictionary.pad(), + left_to_right=True + ) + + # Embed the source. + x = self.embed_tokens(src_tokens) + + # Apply dropout. + x = self.dropout(x) + + # Pack the sequence into a PackedSequence object to feed to the LSTM. + x = nn.utils.rnn.pack_padded_sequence(x, src_lengths, batch_first=True) + + # Get the output from the LSTM. + _outputs, (final_hidden, _final_cell) = self.lstm(x) + + # Return the Encoder's output. This can be any object and will be + # passed directly to the Decoder. + return { + # this will have shape `(bsz, hidden_dim)` + 'final_hidden': final_hidden.squeeze(0), + } + + # Encoders are required to implement this method so that we can rearrange + # the order of the batch elements during inference (e.g., beam search). + def reorder_encoder_out(self, encoder_out, new_order): + """ + Reorder encoder output according to `new_order`. + + Args: + encoder_out: output from the ``forward()`` method + new_order (LongTensor): desired order + + Returns: + `encoder_out` rearranged according to `new_order` + """ + final_hidden = encoder_out['final_hidden'] + return { + 'final_hidden': final_hidden.index_select(0, new_order), + } + + +Decoder +~~~~~~~ + +Our Decoder will predict the next word, conditioned on the Encoder's final +hidden state and an embedded representation of the previous target word -- which +is sometimes called *teacher forcing*. More specifically, we'll use a +:class:`torch.nn.LSTM` to produce a sequence of hidden states that we'll project +to the size of the output vocabulary to predict each target word. + +:: + + import torch + from fairseq.models import FairseqDecoder + + class SimpleLSTMDecoder(FairseqDecoder): + + def __init__( + self, dictionary, encoder_hidden_dim=128, embed_dim=128, hidden_dim=128, + dropout=0.1, + ): + super().__init__(dictionary) + + # Our decoder will embed the inputs before feeding them to the LSTM. + self.embed_tokens = nn.Embedding( + num_embeddings=len(dictionary), + embedding_dim=embed_dim, + padding_idx=dictionary.pad(), + ) + self.dropout = nn.Dropout(p=dropout) + + # We'll use a single-layer, unidirectional LSTM for simplicity. + self.lstm = nn.LSTM( + # For the first layer we'll concatenate the Encoder's final hidden + # state with the embedded target tokens. + input_size=encoder_hidden_dim + embed_dim, + hidden_size=hidden_dim, + num_layers=1, + bidirectional=False, + ) + + # Define the output projection. + self.output_projection = nn.Linear(hidden_dim, len(dictionary)) + + # During training Decoders are expected to take the entire target sequence + # (shifted right by one position) and produce logits over the vocabulary. + # The *prev_output_tokens* tensor begins with the end-of-sentence symbol, + # ``dictionary.eos()``, followed by the target sequence. + def forward(self, prev_output_tokens, encoder_out): + """ + Args: + prev_output_tokens (LongTensor): previous decoder outputs of shape + `(batch, tgt_len)`, for teacher forcing + encoder_out (Tensor, optional): output from the encoder, used for + encoder-side attention + + Returns: + tuple: + - the last decoder layer's output of shape + `(batch, tgt_len, vocab)` + - the last decoder layer's attention weights of shape + `(batch, tgt_len, src_len)` + """ + bsz, tgt_len = prev_output_tokens.size() + + # Extract the final hidden state from the Encoder. + final_encoder_hidden = encoder_out['final_hidden'] + + # Embed the target sequence, which has been shifted right by one + # position and now starts with the end-of-sentence symbol. + x = self.embed_tokens(prev_output_tokens) + + # Apply dropout. + x = self.dropout(x) + + # Concatenate the Encoder's final hidden state to *every* embedded + # target token. + x = torch.cat( + [x, final_encoder_hidden.unsqueeze(1).expand(bsz, tgt_len, -1)], + dim=2, + ) + + # Using PackedSequence objects in the Decoder is harder than in the + # Encoder, since the targets are not sorted in descending length order, + # which is a requirement of ``pack_padded_sequence()``. Instead we'll + # feed nn.LSTM directly. + initial_state = ( + final_encoder_hidden.unsqueeze(0), # hidden + torch.zeros_like(final_encoder_hidden).unsqueeze(0), # cell + ) + output, _ = self.lstm( + x.transpose(0, 1), # convert to shape `(tgt_len, bsz, dim)` + initial_state, + ) + x = output.transpose(0, 1) # convert to shape `(bsz, tgt_len, hidden)` + + # Project the outputs to the size of the vocabulary. + x = self.output_projection(x) + + # Return the logits and ``None`` for the attention weights + return x, None + + +2. Registering the Model +------------------------ + +Now that we've defined our Encoder and Decoder we must *register* our model with +fairseq using the :func:`~fairseq.models.register_model` function decorator. +Once the model is registered we'll be able to use it with the existing +:ref:`Command-line Tools`. + +All registered models must implement the +:class:`~fairseq.models.BaseFairseqModel` interface. For sequence-to-sequence +models (i.e., any model with a single Encoder and Decoder), we can instead +implement the :class:`~fairseq.models.FairseqEncoderDecoderModel` interface. + +Create a small wrapper class in the same file and register it in fairseq with +the name ``'simple_lstm'``:: + + from fairseq.models import FairseqEncoderDecoderModel, register_model + + # Note: the register_model "decorator" should immediately precede the + # definition of the Model class. + + @register_model('simple_lstm') + class SimpleLSTMModel(FairseqEncoderDecoderModel): + + @staticmethod + def add_args(parser): + # Models can override this method to add new command-line arguments. + # Here we'll add some new command-line arguments to configure dropout + # and the dimensionality of the embeddings and hidden states. + parser.add_argument( + '--encoder-embed-dim', type=int, metavar='N', + help='dimensionality of the encoder embeddings', + ) + parser.add_argument( + '--encoder-hidden-dim', type=int, metavar='N', + help='dimensionality of the encoder hidden state', + ) + parser.add_argument( + '--encoder-dropout', type=float, default=0.1, + help='encoder dropout probability', + ) + parser.add_argument( + '--decoder-embed-dim', type=int, metavar='N', + help='dimensionality of the decoder embeddings', + ) + parser.add_argument( + '--decoder-hidden-dim', type=int, metavar='N', + help='dimensionality of the decoder hidden state', + ) + parser.add_argument( + '--decoder-dropout', type=float, default=0.1, + help='decoder dropout probability', + ) + + @classmethod + def build_model(cls, args, task): + # Fairseq initializes models by calling the ``build_model()`` + # function. This provides more flexibility, since the returned model + # instance can be of a different type than the one that was called. + # In this case we'll just return a SimpleLSTMModel instance. + + # Initialize our Encoder and Decoder. + encoder = SimpleLSTMEncoder( + args=args, + dictionary=task.source_dictionary, + embed_dim=args.encoder_embed_dim, + hidden_dim=args.encoder_hidden_dim, + dropout=args.encoder_dropout, + ) + decoder = SimpleLSTMDecoder( + dictionary=task.target_dictionary, + encoder_hidden_dim=args.encoder_hidden_dim, + embed_dim=args.decoder_embed_dim, + hidden_dim=args.decoder_hidden_dim, + dropout=args.decoder_dropout, + ) + model = SimpleLSTMModel(encoder, decoder) + + # Print the model architecture. + print(model) + + return model + + # We could override the ``forward()`` if we wanted more control over how + # the encoder and decoder interact, but it's not necessary for this + # tutorial since we can inherit the default implementation provided by + # the FairseqEncoderDecoderModel base class, which looks like: + # + # def forward(self, src_tokens, src_lengths, prev_output_tokens): + # encoder_out = self.encoder(src_tokens, src_lengths) + # decoder_out = self.decoder(prev_output_tokens, encoder_out) + # return decoder_out + +Finally let's define a *named architecture* with the configuration for our +model. This is done with the :func:`~fairseq.models.register_model_architecture` +function decorator. Thereafter this named architecture can be used with the +``--arch`` command-line argument, e.g., ``--arch tutorial_simple_lstm``:: + + from fairseq.models import register_model_architecture + + # The first argument to ``register_model_architecture()`` should be the name + # of the model we registered above (i.e., 'simple_lstm'). The function we + # register here should take a single argument *args* and modify it in-place + # to match the desired architecture. + + @register_model_architecture('simple_lstm', 'tutorial_simple_lstm') + def tutorial_simple_lstm(args): + # We use ``getattr()`` to prioritize arguments that are explicitly given + # on the command-line, so that the defaults defined below are only used + # when no other value has been specified. + args.encoder_embed_dim = getattr(args, 'encoder_embed_dim', 256) + args.encoder_hidden_dim = getattr(args, 'encoder_hidden_dim', 256) + args.decoder_embed_dim = getattr(args, 'decoder_embed_dim', 256) + args.decoder_hidden_dim = getattr(args, 'decoder_hidden_dim', 256) + + +3. Training the Model +--------------------- + +Now we're ready to train the model. We can use the existing :ref:`fairseq-train` +command-line tool for this, making sure to specify our new Model architecture +(``--arch tutorial_simple_lstm``). + +.. note:: + + Make sure you've already preprocessed the data from the IWSLT example in the + :file:`examples/translation/` directory. + +.. code-block:: console + + > fairseq-train data-bin/iwslt14.tokenized.de-en \ + --arch tutorial_simple_lstm \ + --encoder-dropout 0.2 --decoder-dropout 0.2 \ + --optimizer adam --lr 0.005 --lr-shrink 0.5 \ + --max-tokens 12000 + (...) + | epoch 052 | loss 4.027 | ppl 16.30 | wps 420805 | ups 39.7 | wpb 9841 | bsz 400 | num_updates 20852 | lr 1.95313e-05 | gnorm 0.218 | clip 0% | oom 0 | wall 529 | train_wall 396 + | epoch 052 | valid on 'valid' subset | valid_loss 4.74989 | valid_ppl 26.91 | num_updates 20852 | best 4.74954 + +The model files should appear in the :file:`checkpoints/` directory. While this +model architecture is not very good, we can use the :ref:`fairseq-generate` script to +generate translations and compute our BLEU score over the test set: + +.. code-block:: console + + > fairseq-generate data-bin/iwslt14.tokenized.de-en \ + --path checkpoints/checkpoint_best.pt \ + --beam 5 \ + --remove-bpe + (...) + | Translated 6750 sentences (153132 tokens) in 17.3s (389.12 sentences/s, 8827.68 tokens/s) + | Generate test with beam=5: BLEU4 = 8.18, 38.8/12.1/4.7/2.0 (BP=1.000, ratio=1.066, syslen=139865, reflen=131146) + + +4. Making generation faster +--------------------------- + +While autoregressive generation from sequence-to-sequence models is inherently +slow, our implementation above is especially slow because it recomputes the +entire sequence of Decoder hidden states for every output token (i.e., it is +``O(n^2)``). We can make this significantly faster by instead caching the +previous hidden states. + +In fairseq this is called :ref:`Incremental decoding`. Incremental decoding is a +special mode at inference time where the Model only receives a single timestep +of input corresponding to the immediately previous output token (for teacher +forcing) and must produce the next output incrementally. Thus the model must +cache any long-term state that is needed about the sequence, e.g., hidden +states, convolutional states, etc. + +To implement incremental decoding we will modify our model to implement the +:class:`~fairseq.models.FairseqIncrementalDecoder` interface. Compared to the +standard :class:`~fairseq.models.FairseqDecoder` interface, the incremental +decoder interface allows ``forward()`` methods to take an extra keyword argument +(*incremental_state*) that can be used to cache state across time-steps. + +Let's replace our ``SimpleLSTMDecoder`` with an incremental one:: + + import torch + from fairseq.models import FairseqIncrementalDecoder + + class SimpleLSTMDecoder(FairseqIncrementalDecoder): + + def __init__( + self, dictionary, encoder_hidden_dim=128, embed_dim=128, hidden_dim=128, + dropout=0.1, + ): + # This remains the same as before. + super().__init__(dictionary) + self.embed_tokens = nn.Embedding( + num_embeddings=len(dictionary), + embedding_dim=embed_dim, + padding_idx=dictionary.pad(), + ) + self.dropout = nn.Dropout(p=dropout) + self.lstm = nn.LSTM( + input_size=encoder_hidden_dim + embed_dim, + hidden_size=hidden_dim, + num_layers=1, + bidirectional=False, + ) + self.output_projection = nn.Linear(hidden_dim, len(dictionary)) + + # We now take an additional kwarg (*incremental_state*) for caching the + # previous hidden and cell states. + def forward(self, prev_output_tokens, encoder_out, incremental_state=None): + if incremental_state is not None: + # If the *incremental_state* argument is not ``None`` then we are + # in incremental inference mode. While *prev_output_tokens* will + # still contain the entire decoded prefix, we will only use the + # last step and assume that the rest of the state is cached. + prev_output_tokens = prev_output_tokens[:, -1:] + + # This remains the same as before. + bsz, tgt_len = prev_output_tokens.size() + final_encoder_hidden = encoder_out['final_hidden'] + x = self.embed_tokens(prev_output_tokens) + x = self.dropout(x) + x = torch.cat( + [x, final_encoder_hidden.unsqueeze(1).expand(bsz, tgt_len, -1)], + dim=2, + ) + + # We will now check the cache and load the cached previous hidden and + # cell states, if they exist, otherwise we will initialize them to + # zeros (as before). We will use the ``utils.get_incremental_state()`` + # and ``utils.set_incremental_state()`` helpers. + initial_state = utils.get_incremental_state( + self, incremental_state, 'prev_state', + ) + if initial_state is None: + # first time initialization, same as the original version + initial_state = ( + final_encoder_hidden.unsqueeze(0), # hidden + torch.zeros_like(final_encoder_hidden).unsqueeze(0), # cell + ) + + # Run one step of our LSTM. + output, latest_state = self.lstm(x.transpose(0, 1), initial_state) + + # Update the cache with the latest hidden and cell states. + utils.set_incremental_state( + self, incremental_state, 'prev_state', latest_state, + ) + + # This remains the same as before + x = output.transpose(0, 1) + x = self.output_projection(x) + return x, None + + # The ``FairseqIncrementalDecoder`` interface also requires implementing a + # ``reorder_incremental_state()`` method, which is used during beam search + # to select and reorder the incremental state. + def reorder_incremental_state(self, incremental_state, new_order): + # Load the cached state. + prev_state = utils.get_incremental_state( + self, incremental_state, 'prev_state', + ) + + # Reorder batches according to *new_order*. + reordered_state = ( + prev_state[0].index_select(1, new_order), # hidden + prev_state[1].index_select(1, new_order), # cell + ) + + # Update the cached state. + utils.set_incremental_state( + self, incremental_state, 'prev_state', reordered_state, + ) + +Finally, we can rerun generation and observe the speedup: + +.. code-block:: console + + # Before + + > fairseq-generate data-bin/iwslt14.tokenized.de-en \ + --path checkpoints/checkpoint_best.pt \ + --beam 5 \ + --remove-bpe + (...) + | Translated 6750 sentences (153132 tokens) in 17.3s (389.12 sentences/s, 8827.68 tokens/s) + | Generate test with beam=5: BLEU4 = 8.18, 38.8/12.1/4.7/2.0 (BP=1.000, ratio=1.066, syslen=139865, reflen=131146) + + # After + + > fairseq-generate data-bin/iwslt14.tokenized.de-en \ + --path checkpoints/checkpoint_best.pt \ + --beam 5 \ + --remove-bpe + (...) + | Translated 6750 sentences (153132 tokens) in 5.5s (1225.54 sentences/s, 27802.94 tokens/s) + | Generate test with beam=5: BLEU4 = 8.18, 38.8/12.1/4.7/2.0 (BP=1.000, ratio=1.066, syslen=139865, reflen=131146) diff --git a/PyTorch/NLP/new-Transformer/env.sh b/PyTorch/NLP/new-Transformer/env.sh new file mode 100644 index 00000000..b8cac538 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/env.sh @@ -0,0 +1,39 @@ + +#module load compiler/intel/2021.3.0 +export ROCM_PATH=/work/home/hepj/app/dtk-22.04.2 + +echo $ROCM_PATH +export HIP_PATH=${ROCM_PATH}/hip +export AMDGPU_TARGETS="gfx900;gfx906" +export PATH=${ROCM_PATH}/bin:${ROCM_PATH}/llvm/bin:${ROCM_PATH}/hcc/bin:${ROCM_PATH}/hip/bin:$PATH + +export LD_LIBRARY_PATH=${ROCM_PATH}/lib:${ROCM_PATH}/lib64:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=${ROCM_PATH}/hip/lib:${ROCM_PATH}/llvm/lib:${ROCM_PATH}/opencl/lib/x86_64:$LD_LIBRARY_PATH +#export LD_LIBRARY_PATH=${ROCM_PATH}/hip/lib:${ROCM_PATH}/llvm/lib:$LD_LIBRARY_PATH +#export C_INCLUDE_PATH=${ROCM_PATH}/include:${ROCM_PATH}/llvm/include${C_INCLUDE_PATH:+:${C_INCLUDE_PATH}} +export C_INCLUDE_PATH=${ROCM_PATH}/include:${ROCM_PATH}/llvm/include:/opencl/include +export CPLUS_INCLUDE_PATH=${ROCM_PATH}/include:${ROCM_PATH}/llvm/include +export PATH=${ROCM_PATH}/miopen/bin:${ROCM_PATH}/rocblas/bin:${ROCM_PATH}/hipsparse/bin:$PATH +export LD_LIBRARY_PATH=${ROCM_PATH}/miopen/lib:${ROCM_PATH}/rocblas/lib:$LD_LIBRARY_PATH +export MIOPEN_SYSTEM_DB_PATH=${ROCM_PATH}/miopen/share/miopen/db/ +export LD_LIBRARY_PATH=/usr/lib64:$LD_LIBRARY_PATH +export LIBRARY_PATH=/usr/lib64:$LIBRARY_PATH + + +export C_INCLUDE_PATH=/public/software/apps/deeplearning-depend/gflags-2.1.2-build/include:/public/software/apps/DeepLearning/PyTorch/glog-build/include:$C_INCLUDE_PATH +export DEEP_PATH=/public/software/apps/deeplearning-depend +export LD_LIBRARY_PATH=/work/home/hepj/.pyenv/versions/3.7.0/envs/torch/lib/python3.7/site-packages/Pillow.libs/:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=/public/software/apps/deeplearning-depend/lmdb-0.9.24-build/lib/:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=/public/software/apps/deeplearning-depend/opencv-2.4.13.6-build/lib/:$LD_LIBRARY_PATH + +export LD_LIBRARY_PATH=${DEEP_PATH}/glog-build/lib/:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=${DEEP_PATH}/opencv-2.4.13.6-build/lib/:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=${DEEP_PATH}/openblas-0.3.7-build/lib/:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=${DEEP_PATH}/gflags-2.1.2-build/lib/:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=${DEEP_PATH}/lib/:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=/public/software/apps/DeepLearning/PyTorch/openmp-build/lib:$LD_LIBRARY_PATH + + +#使用rocblas添加的路径 +export LD_LIBRARY_PATH=/work/home/hepj/app/dtk-22.04.2/lib:$LD_LIBRARY_PATH +export LD_LIBRARY_PATH=/work/home/hepj/app/dtk-22.04.2/rocblas/lib/benchmark_tool:$LD_LIBRARY_PATH \ No newline at end of file diff --git a/PyTorch/NLP/Transformer/examples/.gitignore b/PyTorch/NLP/new-Transformer/examples/.gitignore similarity index 100% rename from PyTorch/NLP/Transformer/examples/.gitignore rename to PyTorch/NLP/new-Transformer/examples/.gitignore diff --git a/PyTorch/NLP/Transformer/examples/translation/README.md b/PyTorch/NLP/new-Transformer/examples/translation/README.md similarity index 100% rename from PyTorch/NLP/Transformer/examples/translation/README.md rename to PyTorch/NLP/new-Transformer/examples/translation/README.md diff --git a/PyTorch/NLP/Transformer/examples/translation/prepare-iwslt14.sh b/PyTorch/NLP/new-Transformer/examples/translation/prepare-iwslt14.sh similarity index 100% rename from PyTorch/NLP/Transformer/examples/translation/prepare-iwslt14.sh rename to PyTorch/NLP/new-Transformer/examples/translation/prepare-iwslt14.sh diff --git a/PyTorch/NLP/Transformer/examples/translation/prepare-wmt14en2de.sh b/PyTorch/NLP/new-Transformer/examples/translation/prepare-wmt14en2de.sh similarity index 100% rename from PyTorch/NLP/Transformer/examples/translation/prepare-wmt14en2de.sh rename to PyTorch/NLP/new-Transformer/examples/translation/prepare-wmt14en2de.sh diff --git a/PyTorch/NLP/Transformer/examples/translation/prepare-wmt14en2fr.sh b/PyTorch/NLP/new-Transformer/examples/translation/prepare-wmt14en2fr.sh similarity index 100% rename from PyTorch/NLP/Transformer/examples/translation/prepare-wmt14en2fr.sh rename to PyTorch/NLP/new-Transformer/examples/translation/prepare-wmt14en2fr.sh diff --git a/PyTorch/NLP/new-Transformer/fairseq/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/__init__.py new file mode 100644 index 00000000..080c988b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/__init__.py @@ -0,0 +1,45 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +import os +import sys + +try: + from .version import __version__ # noqa +except ImportError: + version_txt = os.path.join(os.path.dirname(__file__), "version.txt") + with open(version_txt) as f: + __version__ = f.read().strip() + +__all__ = ["pdb"] + +# backwards compatibility to support `from fairseq.X import Y` +from fairseq.distributed import utils as distributed_utils +from fairseq.logging import meters, metrics, progress_bar # noqa + +sys.modules["fairseq.distributed_utils"] = distributed_utils +sys.modules["fairseq.meters"] = meters +sys.modules["fairseq.metrics"] = metrics +sys.modules["fairseq.progress_bar"] = progress_bar + +# initialize hydra +from fairseq.dataclass.initialize import hydra_init + +hydra_init() + +import fairseq.criterions # noqa +import fairseq.distributed # noqa +import fairseq.models # noqa +import fairseq.modules # noqa +import fairseq.optim # noqa +import fairseq.optim.lr_scheduler # noqa +import fairseq.pdb # noqa +import fairseq.scoring # noqa +import fairseq.tasks # noqa +import fairseq.token_generation_constraints # noqa + +import fairseq.benchmark # noqa +import fairseq.model_parallel # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/benchmark/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/benchmark/__init__.py new file mode 100644 index 00000000..0317d5c6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/benchmark/__init__.py @@ -0,0 +1,7 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +# import models/tasks to register them +from . import dummy_dataset, dummy_lm, dummy_masked_lm, dummy_model, dummy_mt # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/benchmark/benchmark_multihead_attention.py b/PyTorch/NLP/new-Transformer/fairseq/benchmark/benchmark_multihead_attention.py new file mode 100644 index 00000000..a44847f2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/benchmark/benchmark_multihead_attention.py @@ -0,0 +1,172 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import itertools +import random + +import torch +from torch.utils import benchmark + +from fairseq.modules.multihead_attention import MultiheadAttention + +BATCH = [20, 41, 97] +SEQ = 64 +EMB = 48 +HEADS = 4 +DROP = 0.1 +DEVICE = torch.device("cuda") +ATTN_MASK_DTYPE = [torch.uint8, torch.bool, torch.float] +KEY_PADDING_MASK_DTYPE = [torch.uint8, torch.bool] + + +def _reset_seeds(): + torch.manual_seed(0) + random.seed(0) + + +def _get_mask(to_dtype: torch.dtype, dim0: int, dim1: int): + if to_dtype == torch.float: + mask = torch.randint(0, 2, (dim0, dim1)).to(dtype=torch.bool) + return mask.to(dtype=to_dtype).masked_fill(mask, -float("inf")) + return torch.randint(0, 2, (dim0, dim1)).to(dtype=to_dtype) + + +def benchmark_multihead_attention( + label="", + attn_dtype=torch.uint8, + key_padding_dtype=torch.uint8, + add_bias_kv=False, + add_zero_attn=False, + static_kv=False, + batch_size=20, + embedding=EMB, + seq_len=SEQ, + num_heads=HEADS, +): + + results = [] + # device = torch.device("cuda") + + xformers_att_config = '{"name": "scaled_dot_product"}' + + attn_mask = _get_mask(to_dtype=attn_dtype, dim0=seq_len, dim1=seq_len) + key_padding_mask = _get_mask( + to_dtype=key_padding_dtype, dim0=batch_size, dim1=seq_len + ) + + q = torch.rand(seq_len, batch_size, embedding, requires_grad=True) + k = torch.rand(seq_len, batch_size, embedding, requires_grad=True) + v = torch.rand(seq_len, batch_size, embedding, requires_grad=True) + + _reset_seeds() + + original_mha = MultiheadAttention( + embedding, + num_heads, + dropout=0.0, + xformers_att_config=None, + add_bias_kv=add_bias_kv, + add_zero_attn=add_zero_attn, + ) + + xformers_mha = MultiheadAttention( + embedding, + num_heads, + dropout=0.0, + xformers_att_config=xformers_att_config, + add_bias_kv=add_bias_kv, + add_zero_attn=add_zero_attn, + ) + + def original_bench_fw(q, k, v, key_padding_mask, attn_mask, static_kv): + original_mha( + query=q, + key=k, + value=v, + key_padding_mask=key_padding_mask, + attn_mask=attn_mask, + static_kv=static_kv, + ) + + def xformers_bench_fw(q, k, v, key_padding_mask, attn_mask, static_kv): + xformers_mha( + query=q, + key=k, + value=v, + key_padding_mask=key_padding_mask, + attn_mask=attn_mask, + static_kv=static_kv, + ) + + def original_bench_fw_bw(q, k, v, key_padding_mask, attn_mask, static_kv): + output, _ = original_mha( + query=q, + key=k, + value=v, + key_padding_mask=key_padding_mask, + attn_mask=attn_mask, + static_kv=static_kv, + ) + loss = torch.norm(output) + loss.backward() + + def xformers_bench_fw_bw(q, k, v, key_padding_mask, attn_mask, static_kv): + output, _ = xformers_mha( + query=q, + key=k, + value=v, + key_padding_mask=key_padding_mask, + attn_mask=attn_mask, + static_kv=static_kv, + ) + loss = torch.norm(output) + loss.backward() + + fns = [ + original_bench_fw, + xformers_bench_fw, + original_bench_fw_bw, + xformers_bench_fw_bw, + ] + + for fn in fns: + results.append( + benchmark.Timer( + stmt="fn(q, k, v, key_padding_mask, attn_mask, static_kv)", + globals={ + "q": q, + "k": k, + "v": v, + "key_padding_mask": key_padding_mask, + "attn_mask": attn_mask, + "static_kv": static_kv, + "fn": fn, + }, + label="multihead fw + bw", + sub_label=f"{fn.__name__}", + description=label, + ).blocked_autorange(min_run_time=1) + ) + + compare = benchmark.Compare(results) + compare.print() + + +def run_benchmarks(): + for attn_dtype, key_padding_dtype, add_bias_kv, add_zero_attn in itertools.product( + ATTN_MASK_DTYPE, KEY_PADDING_MASK_DTYPE, [True, False], [True, False] + ): + label = f"attn_dtype {attn_dtype}, key_padding_dtype {key_padding_dtype}, \ + add_bias_kv {add_bias_kv}, add_zero_attn {add_zero_attn}" + benchmark_multihead_attention( + label=label, + attn_dtype=attn_dtype, + key_padding_dtype=key_padding_dtype, + add_bias_kv=add_bias_kv, + add_zero_attn=add_zero_attn, + ) + + +run_benchmarks() diff --git a/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_dataset.py new file mode 100644 index 00000000..2f051754 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_dataset.py @@ -0,0 +1,36 @@ +import numpy as np +from fairseq.data import FairseqDataset + + +class DummyDataset(FairseqDataset): + def __init__(self, batch, num_items, item_size): + super().__init__() + self.batch = batch + self.num_items = num_items + self.item_size = item_size + + def __getitem__(self, index): + return index + + def __len__(self): + return self.num_items + + def collater(self, samples): + return self.batch + + @property + def sizes(self): + return np.array([self.item_size] * self.num_items) + + def num_tokens(self, index): + return self.item_size + + def size(self, index): + return self.item_size + + def ordered_indices(self): + return np.arange(self.num_items) + + @property + def supports_prefetch(self): + return False diff --git a/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_lm.py b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_lm.py new file mode 100644 index 00000000..c6246a0c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_lm.py @@ -0,0 +1,83 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from dataclasses import dataclass, field +from typing import Optional + +import torch +from .dummy_dataset import DummyDataset +from fairseq.data import Dictionary +from fairseq.dataclass import FairseqDataclass +from fairseq.tasks import FairseqTask, register_task +from omegaconf import II + + +logger = logging.getLogger(__name__) + + +@dataclass +class DummyLMConfig(FairseqDataclass): + dict_size: int = 49996 + dataset_size: int = 100000 + tokens_per_sample: int = field( + default=512, metadata={"help": "max sequence length"} + ) + add_bos_token: bool = False + batch_size: Optional[int] = II("dataset.batch_size") + max_tokens: Optional[int] = II("dataset.max_tokens") + max_target_positions: int = II("task.tokens_per_sample") + + +@register_task("dummy_lm", dataclass=DummyLMConfig) +class DummyLMTask(FairseqTask): + def __init__(self, cfg: DummyLMConfig): + super().__init__(cfg) + + # load dictionary + self.dictionary = Dictionary() + for i in range(cfg.dict_size): + self.dictionary.add_symbol("word{}".format(i)) + self.dictionary.pad_to_multiple_(8) # often faster if divisible by 8 + logger.info("dictionary: {} types".format(len(self.dictionary))) + + seq = torch.arange(cfg.tokens_per_sample + 1) + self.dictionary.pad() + 1 + + self.dummy_src = seq[:-1] + self.dummy_tgt = seq[1:] + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + Args: + split (str): name of the split (e.g., train, valid, test) + """ + if self.cfg.batch_size is not None: + bsz = self.cfg.batch_size + else: + bsz = max(1, self.cfg.max_tokens // self.cfg.tokens_per_sample) + self.datasets[split] = DummyDataset( + { + "id": 1, + "net_input": { + "src_tokens": torch.stack([self.dummy_src for _ in range(bsz)]), + "src_lengths": torch.full( + (bsz,), self.cfg.tokens_per_sample, dtype=torch.long + ), + }, + "target": torch.stack([self.dummy_tgt for _ in range(bsz)]), + "nsentences": bsz, + "ntokens": bsz * self.cfg.tokens_per_sample, + }, + num_items=self.cfg.dataset_size, + item_size=self.cfg.tokens_per_sample, + ) + + @property + def source_dictionary(self): + return self.dictionary + + @property + def target_dictionary(self): + return self.dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_masked_lm.py b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_masked_lm.py new file mode 100644 index 00000000..12b9c5d0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_masked_lm.py @@ -0,0 +1,94 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from dataclasses import dataclass, field +from typing import Optional + +import torch +from omegaconf import II + +from .dummy_dataset import DummyDataset +from fairseq.data import Dictionary +from fairseq.dataclass import FairseqDataclass +from fairseq.tasks import FairseqTask, register_task + +logger = logging.getLogger(__name__) + + +@dataclass +class DummyMaskedLMConfig(FairseqDataclass): + dict_size: int = 49996 + dataset_size: int = 100000 + tokens_per_sample: int = field( + default=512, + metadata={ + "help": "max number of total tokens over all" + " segments per sample for BERT dataset" + }, + ) + batch_size: Optional[int] = II("dataset.batch_size") + max_tokens: Optional[int] = II("dataset.max_tokens") + max_target_positions: int = II("task.tokens_per_sample") + + +@register_task("dummy_masked_lm", dataclass=DummyMaskedLMConfig) +class DummyMaskedLMTask(FairseqTask): + def __init__(self, cfg: DummyMaskedLMConfig): + super().__init__(cfg) + + self.dictionary = Dictionary() + for i in range(cfg.dict_size): + self.dictionary.add_symbol("word{}".format(i)) + logger.info("dictionary: {} types".format(len(self.dictionary))) + # add mask token + self.mask_idx = self.dictionary.add_symbol("") + self.dictionary.pad_to_multiple_(8) # often faster if divisible by 8 + + mask_idx = 0 + pad_idx = 1 + seq = torch.arange(cfg.tokens_per_sample) + pad_idx + 1 + mask = torch.arange(2, cfg.tokens_per_sample, 7) # ~15% + src = seq.clone() + src[mask] = mask_idx + tgt = torch.full_like(seq, pad_idx) + tgt[mask] = seq[mask] + + self.dummy_src = src + self.dummy_tgt = tgt + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + Args: + split (str): name of the split (e.g., train, valid, test) + """ + if self.cfg.batch_size is not None: + bsz = self.cfg.batch_size + else: + bsz = max(1, self.cfg.max_tokens // self.cfg.tokens_per_sample) + self.datasets[split] = DummyDataset( + { + "id": 1, + "net_input": { + "src_tokens": torch.stack([self.dummy_src for _ in range(bsz)]), + "src_lengths": torch.full( + (bsz,), self.cfg.tokens_per_sample, dtype=torch.long + ), + }, + "target": torch.stack([self.dummy_tgt for _ in range(bsz)]), + "nsentences": bsz, + "ntokens": bsz * self.cfg.tokens_per_sample, + }, + num_items=self.cfg.dataset_size, + item_size=self.cfg.tokens_per_sample, + ) + + @property + def source_dictionary(self): + return self.dictionary + + @property + def target_dictionary(self): + return self.dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_model.py b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_model.py new file mode 100644 index 00000000..ff26e4fe --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_model.py @@ -0,0 +1,96 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn as nn +import torch.nn.functional as F +from fairseq.data import Dictionary +from fairseq.models import ( + FairseqDecoder, + FairseqLanguageModel, + register_model, + register_model_architecture, +) + + +@register_model("dummy_model") +class DummyModel(FairseqLanguageModel): + def __init__(self, args, encoder): + super().__init__(encoder) + self.args = args + + @staticmethod + def add_args(parser): + parser.add_argument("--num-layers", type=int, default=24) + parser.add_argument("--embed-dim", type=int, default=1024) + + @classmethod + def build_model(cls, args, task): + encoder = DummyEncoder( + num_embed=len(task.target_dictionary), + embed_dim=args.embed_dim, + num_layers=args.num_layers, + ) + return cls(args, encoder) + + def forward(self, src_tokens, masked_tokens=None, **kwargs): + return self.decoder(src_tokens, masked_tokens=masked_tokens) + + +class DummyEncoder(FairseqDecoder): + def __init__(self, num_embed=50000, embed_dim=1024, num_layers=24): + super().__init__(Dictionary()) + self.embed = nn.Embedding( + num_embeddings=num_embed, embedding_dim=embed_dim, padding_idx=0 + ) + self.layers_a = nn.ModuleList( + [ + nn.Sequential( + nn.LayerNorm(embed_dim), + nn.Linear(embed_dim, 3 * embed_dim), # q, k, v input projection + nn.Linear(3 * embed_dim, embed_dim), # skip self-attention + nn.Linear(embed_dim, embed_dim), # output projection + nn.Dropout(), + ) + for i in range(num_layers) + ] + ) + self.layers_b = nn.ModuleList( + [ + nn.Sequential( + nn.LayerNorm(embed_dim), + nn.Linear(embed_dim, 4 * embed_dim), # FFN + nn.ReLU(), + nn.Linear(4 * embed_dim, embed_dim), # FFN + nn.Dropout(0.1), + ) + for i in range(num_layers) + ] + ) + self.out_proj = nn.Linear(embed_dim, num_embed) + + def forward(self, tokens, masked_tokens=None): + x = self.embed(tokens) + for layer_a, layer_b in zip(self.layers_a, self.layers_b): + x = x + layer_a(x) + x = x + layer_b(x) + x = self.out_proj(x) + if masked_tokens is not None: + x = x[masked_tokens] + return (x,) + + def max_positions(self): + return 1024 + + def get_normalized_probs(self, net_output, log_probs, sample=None): + logits = net_output[0].float() + if log_probs: + return F.log_softmax(logits, dim=-1) + else: + return F.softmax(logits, dim=-1) + + +@register_model_architecture("dummy_model", "dummy_model") +def base_architecture(args): + pass diff --git a/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_mt.py b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_mt.py new file mode 100644 index 00000000..28d78cff --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/benchmark/dummy_mt.py @@ -0,0 +1,119 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import numpy as np +import torch + +from fairseq.data import Dictionary, FairseqDataset +from fairseq.tasks import LegacyFairseqTask, register_task + +logger = logging.getLogger(__name__) + + +@register_task("dummy_mt") +class DummyMTTask(LegacyFairseqTask): + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + parser.add_argument("--dict-size", default=49996, type=int) + parser.add_argument("--dataset-size", default=100000, type=int) + parser.add_argument("--src-len", default=30, type=int) + parser.add_argument("--tgt-len", default=30, type=int) + + def __init__(self, args, dictionary): + super().__init__(args) + self.dictionary = dictionary + self.seed = args.seed + + dictionary.pad_to_multiple_(8) # often faster if divisible by 8 + + self.dummy_src = torch.arange(args.src_len + 1) + dictionary.pad() + 1 + self.dummy_tgt = torch.arange(args.tgt_len + 1) + dictionary.pad() + 1 + + @classmethod + def setup_task(cls, args, **kwargs): + """Setup the task.""" + dictionary = Dictionary() + for i in range(args.dict_size): + dictionary.add_symbol("word{}".format(i)) + logger.info("dictionary: {} types".format(len(dictionary))) + + args.max_source_positions = args.src_len + dictionary.pad() + 2 + args.max_target_positions = args.tgt_len + dictionary.pad() + 2 + + return cls(args, dictionary) + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + Args: + split (str): name of the split (e.g., train, valid, test) + """ + item_size = max(self.args.src_len, self.args.tgt_len) + if self.args.batch_size is not None: + bsz = self.args.batch_size + else: + bsz = max(1, self.args.max_tokens // item_size) + tgt = torch.stack([self.dummy_tgt for _ in range(bsz)]) + self.datasets[split] = DummyDataset( + { + "id": 1, + "net_input": { + "src_tokens": torch.stack([self.dummy_src for _ in range(bsz)]), + "src_lengths": torch.full( + (bsz,), self.args.src_len, dtype=torch.long + ), + "prev_output_tokens": tgt.clone(), + }, + "target": tgt, + "nsentences": bsz, + "ntokens": bsz * self.args.tgt_len, + }, + num_items=self.args.dataset_size, + item_size=item_size, + ) + + @property + def source_dictionary(self): + return self.dictionary + + @property + def target_dictionary(self): + return self.dictionary + + +class DummyDataset(FairseqDataset): + def __init__(self, batch, num_items, item_size): + super().__init__() + self.batch = batch + self.num_items = num_items + self.item_size = item_size + + def __getitem__(self, index): + return index + + def __len__(self): + return self.num_items + + def collater(self, samples): + return self.batch + + @property + def sizes(self): + return np.array([self.item_size] * self.num_items) + + def num_tokens(self, index): + return self.item_size + + def size(self, index): + return self.item_size + + def ordered_indices(self): + return np.arange(self.num_items) + + @property + def supports_prefetch(self): + return False diff --git a/PyTorch/NLP/new-Transformer/fairseq/binarizer.py b/PyTorch/NLP/new-Transformer/fairseq/binarizer.py new file mode 100644 index 00000000..6f03d7a2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/binarizer.py @@ -0,0 +1,381 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +import typing as tp +from abc import ABC, abstractmethod +from collections import Counter +from dataclasses import dataclass +from multiprocessing import Pool + +import torch + +from fairseq.data import Dictionary, indexed_dataset +from fairseq.file_chunker_utils import Chunker, find_offsets +from fairseq.file_io import PathManager +from fairseq.tokenizer import tokenize_line + +logger = logging.getLogger("binarizer") + + +@dataclass +class BinarizeSummary: + """ + Keep track of what's going on in the binarizer + """ + + num_seq: int = 0 + replaced: tp.Optional[Counter] = None + num_tok: int = 0 + + @property + def num_replaced(self) -> int: + if self.replaced is None: + return 0 + return sum(self.replaced.values()) + + @property + def replaced_percent(self) -> float: + return 100 * self.num_replaced / self.num_tok + + def __str__(self) -> str: + base = f"{self.num_seq} sents, {self.num_tok} tokens" + if self.replaced is None: + return base + + return f"{base}, {self.replaced_percent:.3}% replaced" + + def merge(self, other: "BinarizeSummary"): + replaced = None + if self.replaced is not None: + replaced = self.replaced + if other.replaced is not None: + if replaced is None: + replaced = other.replaced + else: + replaced += other.replaced + self.replaced = replaced + self.num_seq += other.num_seq + self.num_tok += other.num_tok + + +class Binarizer(ABC): + """ + a binarizer describes how to take a string and build a tensor out of it + """ + + @abstractmethod + def binarize_line( + self, + line: str, + summary: BinarizeSummary, + ) -> torch.IntTensor: + ... + + +def _worker_prefix(output_prefix: str, worker_id: int): + return f"{output_prefix}.pt{worker_id}" + + +class FileBinarizer: + """ + An file binarizer can take a file, tokenize it, and binarize each line to a tensor + """ + + @classmethod + def multiprocess_dataset( + cls, + input_file: str, + dataset_impl: str, + binarizer: Binarizer, + output_prefix: str, + vocab_size=None, + num_workers=1, + ) -> BinarizeSummary: + final_summary = BinarizeSummary() + + offsets = find_offsets(input_file, num_workers) + # find_offsets returns a list of position [pos1, pos2, pos3, pos4] but we would want pairs: + # [(pos1, pos2), (pos2, pos3), (pos3, pos4)] to process the chunks with start/end info + # we zip the list with itself shifted by one to get all the pairs. + (first_chunk, *more_chunks) = zip(offsets, offsets[1:]) + pool = None + if num_workers > 1: + pool = Pool(processes=num_workers - 1) + worker_results = [ + pool.apply_async( + cls._binarize_chunk_and_finalize, + args=( + binarizer, + input_file, + start_offset, + end_offset, + _worker_prefix( + output_prefix, + worker_id, + ), + dataset_impl, + ), + kwds={ + "vocab_size": vocab_size, + } + if vocab_size is not None + else {}, + ) + for worker_id, (start_offset, end_offset) in enumerate( + more_chunks, start=1 + ) + ] + + pool.close() + pool.join() + for r in worker_results: + summ = r.get() + final_summary.merge(summ) + + # do not close the bin file as we need to merge the worker results in + final_ds, summ = cls._binarize_file_chunk( + binarizer, + input_file, + offset_start=first_chunk[0], + offset_end=first_chunk[1], + output_prefix=output_prefix, + dataset_impl=dataset_impl, + vocab_size=vocab_size if vocab_size is not None else None, + ) + final_summary.merge(summ) + + if num_workers > 1: + for worker_id in range(1, num_workers): + # merge the worker outputs + worker_output_prefix = _worker_prefix( + output_prefix, + worker_id, + ) + final_ds.merge_file_(worker_output_prefix) + try: + os.remove(indexed_dataset.data_file_path(worker_output_prefix)) + os.remove(indexed_dataset.index_file_path(worker_output_prefix)) + except Exception as e: + logger.error( + f"couldn't remove {worker_output_prefix}.*", exc_info=e + ) + + # now we can close the file + idx_file = indexed_dataset.index_file_path(output_prefix) + final_ds.finalize(idx_file) + return final_summary + + @staticmethod + def _binarize_file_chunk( + binarizer: Binarizer, + filename: str, + offset_start: int, + offset_end: int, + output_prefix: str, + dataset_impl: str, + vocab_size=None, + ) -> tp.Tuple[tp.Any, BinarizeSummary]: # (dataset builder, BinarizeSummary) + """ + creates a dataset builder and append binarized items to it. This function does not + finalize the builder, this is useful if you want to do other things with your bin file + like appending/merging other files + """ + bin_file = indexed_dataset.data_file_path(output_prefix) + ds = indexed_dataset.make_builder( + bin_file, + impl=dataset_impl, + vocab_size=vocab_size, + ) + summary = BinarizeSummary() + + with Chunker( + PathManager.get_local_path(filename), offset_start, offset_end + ) as line_iterator: + for line in line_iterator: + ds.add_item(binarizer.binarize_line(line, summary)) + + return ds, summary + + @classmethod + def _binarize_chunk_and_finalize( + cls, + binarizer: Binarizer, + filename: str, + offset_start: int, + offset_end: int, + output_prefix: str, + dataset_impl: str, + vocab_size=None, + ): + """ + same as above, but also finalizes the builder + """ + ds, summ = cls._binarize_file_chunk( + binarizer, + filename, + offset_start, + offset_end, + output_prefix, + dataset_impl, + vocab_size=vocab_size, + ) + + idx_file = indexed_dataset.index_file_path(output_prefix) + ds.finalize(idx_file) + + return summ + + +class VocabularyDatasetBinarizer(Binarizer): + """ + Takes a Dictionary/Vocabulary, assign ids to each + token using the dictionary encode_line function. + """ + + def __init__( + self, + dict: Dictionary, + tokenize: tp.Callable[[str], tp.List[str]] = tokenize_line, + append_eos: bool = True, + reverse_order: bool = False, + already_numberized: bool = False, + ) -> None: + self.dict = dict + self.tokenize = tokenize + self.append_eos = append_eos + self.reverse_order = reverse_order + self.already_numberized = already_numberized + super().__init__() + + def binarize_line( + self, + line: str, + summary: BinarizeSummary, + ): + if summary.replaced is None: + summary.replaced = Counter() + + def replaced_consumer(word, idx): + if idx == self.dict.unk_index and word != self.dict.unk_word: + summary.replaced.update([word]) + + if self.already_numberized: + id_strings = line.strip().split() + id_list = [int(id_string) for id_string in id_strings] + if self.reverse_order: + id_list.reverse() + if self.append_eos: + id_list.append(self.dict.eos()) + ids = torch.IntTensor(id_list) + else: + ids = self.dict.encode_line( + line=line, + line_tokenizer=self.tokenize, + add_if_not_exist=False, + consumer=replaced_consumer, + append_eos=self.append_eos, + reverse_order=self.reverse_order, + ) + + summary.num_seq += 1 + summary.num_tok += len(ids) + return ids + + +class AlignmentDatasetBinarizer(Binarizer): + """ + binarize by parsing a set of alignments and packing + them in a tensor (see utils.parse_alignment) + """ + + def __init__( + self, + alignment_parser: tp.Callable[[str], torch.IntTensor], + ) -> None: + super().__init__() + self.alignment_parser = alignment_parser + + def binarize_line( + self, + line: str, + summary: BinarizeSummary, + ): + ids = self.alignment_parser(line) + summary.num_seq += 1 + summary.num_tok += len(ids) + return ids + + +class LegacyBinarizer: + @classmethod + def binarize( + cls, + filename: str, + dico: Dictionary, + consumer: tp.Callable[[torch.IntTensor], None], + tokenize: tp.Callable[[str], tp.List[str]] = tokenize_line, + append_eos: bool = True, + reverse_order: bool = False, + offset: int = 0, + end: int = -1, + already_numberized: bool = False, + ) -> tp.Dict[str, int]: + binarizer = VocabularyDatasetBinarizer( + dict=dico, + tokenize=tokenize, + append_eos=append_eos, + reverse_order=reverse_order, + already_numberized=already_numberized, + ) + return cls._consume_file( + filename, + binarizer, + consumer, + offset_start=offset, + offset_end=end, + ) + + @classmethod + def binarize_alignments( + cls, + filename: str, + alignment_parser: tp.Callable[[str], torch.IntTensor], + consumer: tp.Callable[[torch.IntTensor], None], + offset: int = 0, + end: int = -1, + ) -> tp.Dict[str, int]: + binarizer = AlignmentDatasetBinarizer(alignment_parser) + return cls._consume_file( + filename, + binarizer, + consumer, + offset_start=offset, + offset_end=end, + ) + + @staticmethod + def _consume_file( + filename: str, + binarizer: Binarizer, + consumer: tp.Callable[[torch.IntTensor], None], + offset_start: int, + offset_end: int, + ) -> tp.Dict[str, int]: + summary = BinarizeSummary() + + with Chunker( + PathManager.get_local_path(filename), offset_start, offset_end + ) as line_iterator: + for line in line_iterator: + consumer(binarizer.binarize_line(line, summary)) + + return { + "nseq": summary.num_seq, + "nunk": summary.num_replaced, + "ntok": summary.num_tok, + "replaced": summary.replaced, + } diff --git a/PyTorch/NLP/new-Transformer/fairseq/checkpoint_utils.py b/PyTorch/NLP/new-Transformer/fairseq/checkpoint_utils.py new file mode 100644 index 00000000..aeb04f79 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/checkpoint_utils.py @@ -0,0 +1,901 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import ast +import collections +import contextlib +import inspect +import logging +import os +import re +import time +import traceback +from collections import OrderedDict +from pathlib import Path +from typing import Any, Dict, Optional, Union + +import numpy as np +import torch +from fairseq.data import data_utils +from fairseq.dataclass.configs import CheckpointConfig +from fairseq.dataclass.utils import ( + convert_namespace_to_omegaconf, + overwrite_args_by_name, +) +from fairseq.distributed.fully_sharded_data_parallel import FSDP, has_FSDP +from fairseq.file_io import PathManager +from fairseq.models import FairseqDecoder, FairseqEncoder +from omegaconf import DictConfig, OmegaConf, open_dict + +logger = logging.getLogger(__name__) + + +def save_checkpoint(cfg: CheckpointConfig, trainer, epoch_itr, val_loss): + from fairseq import meters + + # only one worker should attempt to create the required dir + if trainer.data_parallel_rank == 0: + os.makedirs(cfg.save_dir, exist_ok=True) + + prev_best = getattr(save_checkpoint, "best", val_loss) + if val_loss is not None: + best_function = max if cfg.maximize_best_checkpoint_metric else min + save_checkpoint.best = best_function(val_loss, prev_best) + + if cfg.no_save: + return + + trainer.consolidate_optimizer() # TODO(SS): do we need this if no_save_optimizer_state + + if not trainer.should_save_checkpoint_on_current_rank: + if trainer.always_call_state_dict_during_save_checkpoint: + trainer.state_dict() + return + + write_timer = meters.StopwatchMeter() + write_timer.start() + + epoch = epoch_itr.epoch + end_of_epoch = epoch_itr.end_of_epoch() + updates = trainer.get_num_updates() + + logger.info(f"Preparing to save checkpoint for epoch {epoch} @ {updates} updates") + + def is_better(a, b): + return a >= b if cfg.maximize_best_checkpoint_metric else a <= b + + suffix = trainer.checkpoint_suffix + checkpoint_conds = collections.OrderedDict() + checkpoint_conds["checkpoint{}{}.pt".format(epoch, suffix)] = ( + end_of_epoch and not cfg.no_epoch_checkpoints and epoch % cfg.save_interval == 0 + ) + checkpoint_conds["checkpoint_{}_{}{}.pt".format(epoch, updates, suffix)] = ( + not end_of_epoch + and cfg.save_interval_updates > 0 + and updates % cfg.save_interval_updates == 0 + ) + checkpoint_conds["checkpoint_best{}.pt".format(suffix)] = val_loss is not None and ( + not hasattr(save_checkpoint, "best") + or is_better(val_loss, save_checkpoint.best) + ) + if val_loss is not None and cfg.keep_best_checkpoints > 0: + worst_best = getattr(save_checkpoint, "best", None) + chkpts = checkpoint_paths( + cfg.save_dir, + pattern=r"checkpoint\.best_{}_(\d+\.?\d*){}\.pt".format( + cfg.best_checkpoint_metric, suffix + ), + ) + if len(chkpts) > 0: + p = chkpts[-1] if cfg.maximize_best_checkpoint_metric else chkpts[0] + worst_best = float(p.rsplit("_")[-1].replace("{}.pt".format(suffix), "")) + # add random digits to resolve ties + with data_utils.numpy_seed(epoch, updates, val_loss): + rand_sfx = np.random.randint(0, cfg.keep_best_checkpoints) + + checkpoint_conds[ + "checkpoint.best_{}_{:.3f}{}{}.pt".format( + cfg.best_checkpoint_metric, val_loss, rand_sfx, suffix + ) + ] = worst_best is None or is_better(val_loss, worst_best) + checkpoint_conds[ + "checkpoint_last{}.pt".format(suffix) + ] = not cfg.no_last_checkpoints + + extra_state = {"train_iterator": epoch_itr.state_dict(), "val_loss": val_loss} + if hasattr(save_checkpoint, "best"): + extra_state.update({"best": save_checkpoint.best}) + + checkpoints = [ + os.path.join(cfg.save_dir, fn) for fn, cond in checkpoint_conds.items() if cond + ] + if len(checkpoints) > 0 and trainer.should_save_checkpoint_on_current_rank: + trainer.save_checkpoint(checkpoints[0], extra_state) + for cp in checkpoints[1:]: + if cfg.write_checkpoints_asynchronously: + # TODO[ioPath]: Need to implement a delayed asynchronous + # file copying/moving feature. + logger.warning( + f"ioPath is not copying {checkpoints[0]} to {cp} " + "since async write mode is on." + ) + else: + assert PathManager.copy( + checkpoints[0], cp, overwrite=True + ), f"Failed to copy {checkpoints[0]} to {cp}" + + write_timer.stop() + logger.info( + "Saved checkpoint {} (epoch {} @ {} updates, score {}) (writing took {} seconds)".format( + checkpoints[0], epoch, updates, val_loss, write_timer.sum + ) + ) + + if not end_of_epoch and cfg.keep_interval_updates > 0: + # remove old checkpoints; checkpoints are sorted in descending order + if cfg.keep_interval_updates_pattern == -1: + checkpoints = checkpoint_paths( + cfg.save_dir, pattern=r"checkpoint_\d+_(\d+){}\.pt".format(suffix) + ) + else: + checkpoints = checkpoint_paths( + cfg.save_dir, + pattern=r"checkpoint_\d+_(\d+){}\.pt".format(suffix), + keep_match=True, + ) + checkpoints = [ + x[0] + for x in checkpoints + if x[1] % cfg.keep_interval_updates_pattern != 0 + ] + + for old_chk in checkpoints[cfg.keep_interval_updates :]: + if os.path.lexists(old_chk): + os.remove(old_chk) + elif PathManager.exists(old_chk): + PathManager.rm(old_chk) + + if cfg.keep_last_epochs > 0: + # remove old epoch checkpoints; checkpoints are sorted in descending order + checkpoints = checkpoint_paths( + cfg.save_dir, pattern=r"checkpoint(\d+){}\.pt".format(suffix) + ) + for old_chk in checkpoints[cfg.keep_last_epochs :]: + if os.path.lexists(old_chk): + os.remove(old_chk) + elif PathManager.exists(old_chk): + PathManager.rm(old_chk) + + if cfg.keep_best_checkpoints > 0: + # only keep the best N checkpoints according to validation metric + checkpoints = checkpoint_paths( + cfg.save_dir, + pattern=r"checkpoint\.best_{}_(\d+\.?\d*){}\.pt".format( + cfg.best_checkpoint_metric, suffix + ), + ) + if not cfg.maximize_best_checkpoint_metric: + checkpoints = checkpoints[::-1] + for old_chk in checkpoints[cfg.keep_best_checkpoints :]: + if os.path.lexists(old_chk): + os.remove(old_chk) + elif PathManager.exists(old_chk): + PathManager.rm(old_chk) + + +def load_checkpoint(cfg: CheckpointConfig, trainer, **passthrough_args): + """ + Load a checkpoint and restore the training iterator. + + *passthrough_args* will be passed through to + ``trainer.get_train_iterator``. + """ + + reset_optimizer = cfg.reset_optimizer + reset_lr_scheduler = cfg.reset_lr_scheduler + optimizer_overrides = ast.literal_eval(cfg.optimizer_overrides) + reset_meters = cfg.reset_meters + reset_dataloader = cfg.reset_dataloader + + if cfg.finetune_from_model is not None and ( + reset_optimizer or reset_lr_scheduler or reset_meters or reset_dataloader + ): + raise ValueError( + "--finetune-from-model can not be set together with either --reset-optimizer" + " or reset_lr_scheduler or reset_meters or reset_dataloader" + ) + + suffix = trainer.checkpoint_suffix + if ( + cfg.restore_file == "checkpoint_last.pt" + ): # default value of restore_file is 'checkpoint_last.pt' + checkpoint_path = os.path.join( + cfg.save_dir, "checkpoint_last{}.pt".format(suffix) + ) + first_launch = not PathManager.exists(checkpoint_path) + if first_launch and getattr(cfg, "continue_once", None) is not None: + checkpoint_path = cfg.continue_once + elif cfg.finetune_from_model is not None and first_launch: + # if there is no last checkpoint to restore, start the finetune from pretrained model + # else just use usual logic to load checkpoint, e.g. restart from last checkpoint and etc. + if PathManager.exists(cfg.finetune_from_model): + checkpoint_path = cfg.finetune_from_model + reset_optimizer = True + reset_lr_scheduler = True + reset_meters = True + reset_dataloader = True + logger.info( + f"loading pretrained model from {checkpoint_path}: " + "optimizer, lr scheduler, meters, dataloader will be reset" + ) + else: + raise ValueError( + f"--finetune-from-model {cfg.finetune_from_model} does not exist" + ) + elif suffix is not None: + checkpoint_path = cfg.restore_file.replace(".pt", suffix + ".pt") + else: + checkpoint_path = cfg.restore_file + + if cfg.restore_file != "checkpoint_last.pt" and cfg.finetune_from_model: + raise ValueError( + "--finetune-from-model and --restore-file (non-default value) " + "can not be specified together: " + str(cfg) + ) + + extra_state = trainer.load_checkpoint( + checkpoint_path, + reset_optimizer, + reset_lr_scheduler, + optimizer_overrides, + reset_meters=reset_meters, + ) + + if ( + extra_state is not None + and "best" in extra_state + and not reset_optimizer + and not reset_meters + ): + save_checkpoint.best = extra_state["best"] + + if extra_state is not None and not reset_dataloader: + # restore iterator from checkpoint + itr_state = extra_state["train_iterator"] + epoch_itr = trainer.get_train_iterator( + epoch=itr_state["epoch"], load_dataset=True, **passthrough_args + ) + epoch_itr.load_state_dict(itr_state) + else: + epoch_itr = trainer.get_train_iterator( + epoch=1, load_dataset=True, **passthrough_args + ) + + trainer.lr_step(epoch_itr.epoch) + + return extra_state, epoch_itr + + +def load_checkpoint_to_cpu(path, arg_overrides=None, load_on_all_ranks=False): + """Loads a checkpoint to CPU (with upgrading for backward compatibility). + + If doing single-GPU training or if the checkpoint is only being loaded by at + most one process on each node (current default behavior is for only rank 0 + to read the checkpoint from disk), load_on_all_ranks should be False to + avoid errors from torch.distributed not having been initialized or + torch.distributed.barrier() hanging. + + If all processes on each node may be loading the checkpoint + simultaneously, load_on_all_ranks should be set to True to avoid I/O + conflicts. + + There's currently no support for > 1 but < all processes loading the + checkpoint on each node. + """ + local_path = PathManager.get_local_path(path) + # The locally cached file returned by get_local_path() may be stale for + # remote files that are periodically updated/overwritten (ex: + # checkpoint_last.pt) - so we remove the local copy, sync across processes + # (if needed), and then download a fresh copy. + if local_path != path and PathManager.path_requires_pathmanager(path): + try: + os.remove(local_path) + except FileNotFoundError: + # With potentially multiple processes removing the same file, the + # file being missing is benign (missing_ok isn't available until + # Python 3.8). + pass + if load_on_all_ranks: + torch.distributed.barrier() + local_path = PathManager.get_local_path(path) + + with open(local_path, "rb") as f: + state = torch.load(f, map_location=torch.device("cpu")) + + if "args" in state and state["args"] is not None and arg_overrides is not None: + args = state["args"] + for arg_name, arg_val in arg_overrides.items(): + setattr(args, arg_name, arg_val) + + if "cfg" in state and state["cfg"] is not None: + + # hack to be able to set Namespace in dict config. this should be removed when we update to newer + # omegaconf version that supports object flags, or when we migrate all existing models + from omegaconf import _utils + + old_primitive = _utils.is_primitive_type + _utils.is_primitive_type = lambda _: True + + state["cfg"] = OmegaConf.create(state["cfg"]) + + _utils.is_primitive_type = old_primitive + OmegaConf.set_struct(state["cfg"], True) + + if arg_overrides is not None: + overwrite_args_by_name(state["cfg"], arg_overrides) + + state = _upgrade_state_dict(state) + return state + + +def load_model_ensemble( + filenames, + arg_overrides: Optional[Dict[str, Any]] = None, + task=None, + strict=True, + suffix="", + num_shards=1, + state=None, +): + """Loads an ensemble of models. + + Args: + filenames (List[str]): checkpoint files to load + arg_overrides (Dict[str,Any], optional): override model args that + were used during model training + task (fairseq.tasks.FairseqTask, optional): task to use for loading + """ + assert not ( + strict and num_shards > 1 + ), "Cannot load state dict with strict=True and checkpoint shards > 1" + ensemble, args, _task = load_model_ensemble_and_task( + filenames, + arg_overrides, + task, + strict, + suffix, + num_shards, + state, + ) + return ensemble, args + + +def get_maybe_sharded_checkpoint_filename( + filename: str, suffix: str, shard_idx: int, num_shards: int +) -> str: + orig_filename = filename + filename = filename.replace(".pt", suffix + ".pt") + fsdp_filename = filename[:-3] + f"-shard{shard_idx}.pt" + model_parallel_filename = orig_filename[:-3] + f"_part{shard_idx}.pt" + if PathManager.exists(fsdp_filename): + return fsdp_filename + elif num_shards > 1: + return model_parallel_filename + else: + return filename + + +def load_model_ensemble_and_task( + filenames, + arg_overrides: Optional[Dict[str, Any]] = None, + task=None, + strict=True, + suffix="", + num_shards=1, + state=None, +): + assert state is None or len(filenames) == 1 + + from fairseq import tasks + + assert not ( + strict and num_shards > 1 + ), "Cannot load state dict with strict=True and checkpoint shards > 1" + ensemble = [] + cfg = None + for filename in filenames: + orig_filename = filename + model_shard_state = {"shard_weights": [], "shard_metadata": []} + assert num_shards > 0 + st = time.time() + for shard_idx in range(num_shards): + filename = get_maybe_sharded_checkpoint_filename( + orig_filename, suffix, shard_idx, num_shards + ) + + if not PathManager.exists(filename): + raise IOError("Model file not found: {}".format(filename)) + if state is None: + state = load_checkpoint_to_cpu(filename, arg_overrides) + if "args" in state and state["args"] is not None: + cfg = convert_namespace_to_omegaconf(state["args"]) + elif "cfg" in state and state["cfg"] is not None: + cfg = state["cfg"] + else: + raise RuntimeError( + f"Neither args nor cfg exist in state keys = {state.keys()}" + ) + + if task is None: + task = tasks.setup_task(cfg.task) + + if "task_state" in state: + task.load_state_dict(state["task_state"]) + + if "fsdp_metadata" in state and num_shards > 1: + model_shard_state["shard_weights"].append(state["model"]) + model_shard_state["shard_metadata"].append(state["fsdp_metadata"]) + # check FSDP import before the code goes too far + if not has_FSDP: + raise ImportError( + "Cannot find FullyShardedDataParallel. " + "Please install fairscale with: pip install fairscale" + ) + if shard_idx == num_shards - 1: + consolidated_model_state = FSDP.consolidate_shard_weights( + shard_weights=model_shard_state["shard_weights"], + shard_metadata=model_shard_state["shard_metadata"], + ) + model = task.build_model(cfg.model) + if ( + "optimizer_history" in state + and len(state["optimizer_history"]) > 0 + and "num_updates" in state["optimizer_history"][-1] + ): + model.set_num_updates( + state["optimizer_history"][-1]["num_updates"] + ) + model.load_state_dict( + consolidated_model_state, strict=strict, model_cfg=cfg.model + ) + else: + # model parallel checkpoint or unsharded checkpoint + # support old external tasks + + argspec = inspect.getfullargspec(task.build_model) + if "from_checkpoint" in argspec.args: + model = task.build_model(cfg.model, from_checkpoint=True) + else: + model = task.build_model(cfg.model) + if ( + "optimizer_history" in state + and len(state["optimizer_history"]) > 0 + and "num_updates" in state["optimizer_history"][-1] + ): + model.set_num_updates(state["optimizer_history"][-1]["num_updates"]) + model.load_state_dict( + state["model"], strict=strict, model_cfg=cfg.model + ) + + # reset state so it gets loaded for the next model in ensemble + state = None + if shard_idx % 10 == 0 and shard_idx > 0: + elapsed = time.time() - st + logger.info( + f"Loaded {shard_idx} shards in {elapsed:.2f}s, {elapsed / (shard_idx+1):.2f}s/shard" + ) + + # build model for ensemble + ensemble.append(model) + return ensemble, cfg, task + + +def load_model_ensemble_and_task_from_hf_hub( + model_id, + cache_dir: Optional[str] = None, + arg_overrides: Optional[Dict[str, Any]] = None, + **kwargs: Any, +): + try: + from huggingface_hub import snapshot_download + except ImportError: + raise ImportError( + "You need to install huggingface_hub to use `load_from_hf_hub`. " + "See https://pypi.org/project/huggingface-hub/ for installation." + ) + + library_name = "fairseq" + cache_dir = cache_dir or (Path.home() / ".cache" / library_name).as_posix() + cache_dir = snapshot_download( + model_id, cache_dir=cache_dir, library_name=library_name, **kwargs + ) + + _arg_overrides = arg_overrides or {} + _arg_overrides["data"] = cache_dir + return load_model_ensemble_and_task( + [p.as_posix() for p in Path(cache_dir).glob("*.pt")], + arg_overrides=_arg_overrides, + ) + + +def checkpoint_paths(path, pattern=r"checkpoint(\d+)\.pt", keep_match=False): + """Retrieves all checkpoints found in `path` directory. + + Checkpoints are identified by matching filename to the specified pattern. If + the pattern contains groups, the result will be sorted by the first group in + descending order. + """ + pt_regexp = re.compile(pattern) + files = PathManager.ls(path) + + entries = [] + for i, f in enumerate(files): + m = pt_regexp.fullmatch(f) + if m is not None: + idx = float(m.group(1)) if len(m.groups()) > 0 else i + entries.append((idx, m.group(0))) + if keep_match: + return [(os.path.join(path, x[1]), x[0]) for x in sorted(entries, reverse=True)] + else: + return [os.path.join(path, x[1]) for x in sorted(entries, reverse=True)] + + +def torch_persistent_save(obj, filename, async_write: bool = False): + if async_write: + with PathManager.opena(filename, "wb") as f: + _torch_persistent_save(obj, f) + else: + if PathManager.supports_rename(filename): + # do atomic save + with PathManager.open(filename + ".tmp", "wb") as f: + _torch_persistent_save(obj, f) + PathManager.rename(filename + ".tmp", filename) + else: + # fallback to non-atomic save + with PathManager.open(filename, "wb") as f: + _torch_persistent_save(obj, f) + + +def _torch_persistent_save(obj, f): + if isinstance(f, str): + with PathManager.open(f, "wb") as h: + torch_persistent_save(obj, h) + return + for i in range(3): + try: + return torch.save(obj, f) + except Exception: + if i == 2: + logger.error(traceback.format_exc()) + raise + + +def _upgrade_state_dict(state): + """Helper for upgrading old model checkpoints.""" + + # add optimizer_history + if "optimizer_history" not in state: + state["optimizer_history"] = [ + {"criterion_name": "CrossEntropyCriterion", "best_loss": state["best_loss"]} + ] + state["last_optimizer_state"] = state["optimizer"] + del state["optimizer"] + del state["best_loss"] + # move extra_state into sub-dictionary + if "epoch" in state and "extra_state" not in state: + state["extra_state"] = { + "epoch": state["epoch"], + "batch_offset": state["batch_offset"], + "val_loss": state["val_loss"], + } + del state["epoch"] + del state["batch_offset"] + del state["val_loss"] + # reduce optimizer history's memory usage (only keep the last state) + if "optimizer" in state["optimizer_history"][-1]: + state["last_optimizer_state"] = state["optimizer_history"][-1]["optimizer"] + for optim_hist in state["optimizer_history"]: + del optim_hist["optimizer"] + # record the optimizer class name + if "optimizer_name" not in state["optimizer_history"][-1]: + state["optimizer_history"][-1]["optimizer_name"] = "FairseqNAG" + # move best_loss into lr_scheduler_state + if "lr_scheduler_state" not in state["optimizer_history"][-1]: + state["optimizer_history"][-1]["lr_scheduler_state"] = { + "best": state["optimizer_history"][-1]["best_loss"] + } + del state["optimizer_history"][-1]["best_loss"] + # keep track of number of updates + if "num_updates" not in state["optimizer_history"][-1]: + state["optimizer_history"][-1]["num_updates"] = 0 + # use stateful training data iterator + if "train_iterator" not in state["extra_state"]: + state["extra_state"]["train_iterator"] = { + "epoch": state["extra_state"].get("epoch", 0), + "iterations_in_epoch": state["extra_state"].get("batch_offset", 0), + } + + # backward compatibility, cfg updates + if "args" in state and state["args"] is not None: + # old model checkpoints may not have separate source/target positions + if hasattr(state["args"], "max_positions") and not hasattr( + state["args"], "max_source_positions" + ): + state["args"].max_source_positions = state["args"].max_positions + state["args"].max_target_positions = state["args"].max_positions + # default to translation task + if not hasattr(state["args"], "task"): + state["args"].task = "translation" + # --raw-text and --lazy-load are deprecated + if getattr(state["args"], "raw_text", False): + state["args"].dataset_impl = "raw" + elif getattr(state["args"], "lazy_load", False): + state["args"].dataset_impl = "lazy" + # epochs start at 1 + if state["extra_state"]["train_iterator"] is not None: + state["extra_state"]["train_iterator"]["epoch"] = max( + state["extra_state"]["train_iterator"].get("epoch", 1), 1 + ) + # --remove-bpe ==> --postprocess + if hasattr(state["args"], "remove_bpe"): + state["args"].post_process = state["args"].remove_bpe + # --min-lr ==> --stop-min-lr + if hasattr(state["args"], "min_lr"): + state["args"].stop_min_lr = state["args"].min_lr + del state["args"].min_lr + # binary_cross_entropy / kd_binary_cross_entropy => wav2vec criterion + if hasattr(state["args"], "criterion") and state["args"].criterion in [ + "binary_cross_entropy", + "kd_binary_cross_entropy", + ]: + state["args"].criterion = "wav2vec" + # remove log_keys if it's None (criteria will supply a default value of []) + if hasattr(state["args"], "log_keys") and state["args"].log_keys is None: + delattr(state["args"], "log_keys") + # speech_pretraining => audio pretraining + if ( + hasattr(state["args"], "task") + and state["args"].task == "speech_pretraining" + ): + state["args"].task = "audio_pretraining" + # audio_cpc => wav2vec + if hasattr(state["args"], "arch") and state["args"].arch == "audio_cpc": + state["args"].arch = "wav2vec" + # convert legacy float learning rate to List[float] + if hasattr(state["args"], "lr") and isinstance(state["args"].lr, float): + state["args"].lr = [state["args"].lr] + # convert task data arg to a string instead of List[string] + if ( + hasattr(state["args"], "data") + and isinstance(state["args"].data, list) + and len(state["args"].data) > 0 + ): + state["args"].data = state["args"].data[0] + + state["cfg"] = convert_namespace_to_omegaconf(state["args"]) + + if "cfg" in state and state["cfg"] is not None: + cfg = state["cfg"] + with open_dict(cfg): + # any upgrades for Hydra-based configs + if ( + "task" in cfg + and "eval_wer_config" in cfg.task + and isinstance(cfg.task.eval_wer_config.print_alignment, bool) + ): + cfg.task.eval_wer_config.print_alignment = "hard" + if "generation" in cfg and isinstance(cfg.generation.print_alignment, bool): + cfg.generation.print_alignment = ( + "hard" if cfg.generation.print_alignment else None + ) + if ( + "model" in cfg + and "w2v_args" in cfg.model + and cfg.model.w2v_args is not None + and ( + hasattr(cfg.model.w2v_args, "task") or "task" in cfg.model.w2v_args + ) + and hasattr(cfg.model.w2v_args.task, "eval_wer_config") + and cfg.model.w2v_args.task.eval_wer_config is not None + and isinstance( + cfg.model.w2v_args.task.eval_wer_config.print_alignment, bool + ) + ): + cfg.model.w2v_args.task.eval_wer_config.print_alignment = "hard" + + return state + + +def prune_state_dict(state_dict, model_cfg: Optional[DictConfig]): + """Prune the given state_dict if desired for LayerDrop + (https://arxiv.org/abs/1909.11556). + + Training with LayerDrop allows models to be robust to pruning at inference + time. This function prunes state_dict to allow smaller models to be loaded + from a larger model and re-maps the existing state_dict for this to occur. + + It's called by functions that load models from checkpoints and does not + need to be called directly. + """ + arch = None + if model_cfg is not None: + arch = ( + model_cfg._name + if isinstance(model_cfg, DictConfig) + else getattr(model_cfg, "arch", None) + ) + + if not model_cfg or arch is None or arch == "ptt_transformer": + # args should not be none, but don't crash if it is. + return state_dict + + encoder_layers_to_keep = getattr(model_cfg, "encoder_layers_to_keep", None) + decoder_layers_to_keep = getattr(model_cfg, "decoder_layers_to_keep", None) + + if not encoder_layers_to_keep and not decoder_layers_to_keep: + return state_dict + + # apply pruning + logger.info( + "Pruning model to specified layer configuration - this works best if the model was trained with LayerDrop" + ) + + def create_pruning_pass(layers_to_keep, layer_name): + keep_layers = sorted( + int(layer_string) for layer_string in layers_to_keep.split(",") + ) + mapping_dict = {} + for i in range(len(keep_layers)): + mapping_dict[str(keep_layers[i])] = str(i) + + regex = re.compile(r"^{layer}.*\.layers\.(\d+)".format(layer=layer_name)) + return {"substitution_regex": regex, "mapping_dict": mapping_dict} + + pruning_passes = [] + if encoder_layers_to_keep: + pruning_passes.append(create_pruning_pass(encoder_layers_to_keep, "encoder")) + if decoder_layers_to_keep: + pruning_passes.append(create_pruning_pass(decoder_layers_to_keep, "decoder")) + + new_state_dict = {} + for layer_name in state_dict.keys(): + match = re.search(r"\.layers\.(\d+)\.", layer_name) + # if layer has no number in it, it is a supporting layer, such as an + # embedding + if not match: + new_state_dict[layer_name] = state_dict[layer_name] + continue + + # otherwise, layer should be pruned. + original_layer_number = match.group(1) + # figure out which mapping dict to replace from + for pruning_pass in pruning_passes: + if original_layer_number in pruning_pass["mapping_dict"] and pruning_pass[ + "substitution_regex" + ].search(layer_name): + new_layer_number = pruning_pass["mapping_dict"][original_layer_number] + substitution_match = pruning_pass["substitution_regex"].search( + layer_name + ) + new_state_key = ( + layer_name[: substitution_match.start(1)] + + new_layer_number + + layer_name[substitution_match.end(1) :] + ) + new_state_dict[new_state_key] = state_dict[layer_name] + + # Since layers are now pruned, *_layers_to_keep are no longer needed. + # This is more of "It would make it work fix" rather than a proper fix. + if isinstance(model_cfg, DictConfig): + context = open_dict(model_cfg) + else: + context = contextlib.ExitStack() + with context: + if hasattr(model_cfg, "encoder_layers_to_keep"): + model_cfg.encoder_layers_to_keep = None + if hasattr(model_cfg, "decoder_layers_to_keep"): + model_cfg.decoder_layers_to_keep = None + + return new_state_dict + + +def load_pretrained_component_from_model( + component: Union[FairseqEncoder, FairseqDecoder], + checkpoint: str, + strict: bool = True, +): + """ + Load a pretrained FairseqEncoder or FairseqDecoder from checkpoint into the + provided `component` object. If state_dict fails to load, there may be a + mismatch in the architecture of the corresponding `component` found in the + `checkpoint` file. + """ + if not PathManager.exists(checkpoint): + raise IOError("Model file not found: {}".format(checkpoint)) + state = load_checkpoint_to_cpu(checkpoint) + if isinstance(component, FairseqEncoder): + component_type = "encoder" + elif isinstance(component, FairseqDecoder): + component_type = "decoder" + else: + raise ValueError( + "component to load must be either a FairseqEncoder or " + "FairseqDecoder. Loading other component types are not supported." + ) + component_state_dict = OrderedDict() + for key in state["model"].keys(): + if key.startswith(component_type): + # encoder.input_layers.0.0.weight --> input_layers.0.0.weight + component_subkey = key[len(component_type) + 1 :] + component_state_dict[component_subkey] = state["model"][key] + component.load_state_dict(component_state_dict, strict=strict) + return component + + +def verify_checkpoint_directory(save_dir: str) -> None: + if not os.path.exists(save_dir): + os.makedirs(save_dir, exist_ok=True) + temp_file_path = os.path.join(save_dir, "dummy") + try: + with open(temp_file_path, "w"): + pass + except OSError as e: + logger.warning( + "Unable to access checkpoint save directory: {}".format(save_dir) + ) + raise e + else: + os.remove(temp_file_path) + + +def save_ema_as_checkpoint(src_path, dst_path): + state = load_ema_from_checkpoint(src_path) + torch_persistent_save(state, dst_path) + + +def load_ema_from_checkpoint(fpath): + """Loads exponential moving averaged (EMA) checkpoint from input and + returns a model with ema weights. + + Args: + fpath: A string path of checkpoint to load from. + + Returns: + A dict of string keys mapping to various values. The 'model' key + from the returned dict should correspond to an OrderedDict mapping + string parameter names to torch Tensors. + """ + params_dict = collections.OrderedDict() + new_state = None + + with PathManager.open(fpath, "rb") as f: + new_state = torch.load( + f, + map_location=( + lambda s, _: torch.serialization.default_restore_location(s, "cpu") + ), + ) + + # EMA model is stored in a separate "extra state" + model_params = new_state["extra_state"]["ema"] + + for key in list(model_params.keys()): + p = model_params[key] + if isinstance(p, torch.HalfTensor): + p = p.float() + if key not in params_dict: + params_dict[key] = p.clone() + # NOTE: clone() is needed in case of p is a shared parameter + else: + raise ValueError("Key {} is repeated in EMA model params.".format(key)) + + if len(params_dict) == 0: + raise ValueError( + f"Input checkpoint path '{fpath}' does not contain " + "ema model weights, is this model trained with EMA?" + ) + + new_state["model"] = params_dict + return new_state diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/cuda/ngram_repeat_block_cuda.cpp b/PyTorch/NLP/new-Transformer/fairseq/clib/cuda/ngram_repeat_block_cuda.cpp new file mode 100644 index 00000000..70721910 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/cuda/ngram_repeat_block_cuda.cpp @@ -0,0 +1,55 @@ +/* +Copyright (c) Microsoft Corporation. +Licensed under the MIT License. +*/ + +#include +#include + +/* +CPP Binding for CUDA OP +*/ + +// CUDA forward declarations +torch::Tensor ngram_repeat_block_cuda_forward( + torch::Tensor tokens, + torch::Tensor lprobs, + int bsz, + int step, + int beam_size, + int no_repeat_ngram_size); + +#define CHECK_CUDA(x) \ + TORCH_CHECK(x.type().is_cuda(), #x " must be a CUDA tensor") +#define CHECK_CONTIGUOUS(x) \ + TORCH_CHECK(x.is_contiguous(), #x " must be contiguous") +#define CHECK_INPUT(x) \ + CHECK_CUDA(x); \ + CHECK_CONTIGUOUS(x) + +// Input check and call to CUDA OP +// Backward method not required +torch::Tensor ngram_repeat_block_forward( + torch::Tensor tokens, + torch::Tensor lprobs, + int bsz, + int step, + int beam_size, + int no_repeat_ngram_size) { + CHECK_INPUT(tokens); + CHECK_INPUT(lprobs); + assert(bsz > 0); + assert(step >= 0); + assert(beam_size > 0); + assert(no_repeat_ngram_size > 0); + + return ngram_repeat_block_cuda_forward( + tokens, lprobs, bsz, step, beam_size, no_repeat_ngram_size); +} + +PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) { + m.def( + "forward", + &ngram_repeat_block_forward, + "No Repeat Ngram Block forward (CUDA)"); +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/cuda/ngram_repeat_block_cuda_kernel.cu b/PyTorch/NLP/new-Transformer/fairseq/clib/cuda/ngram_repeat_block_cuda_kernel.cu new file mode 100644 index 00000000..bd6106cb --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/cuda/ngram_repeat_block_cuda_kernel.cu @@ -0,0 +1,82 @@ +/* +Copyright (c) Microsoft Corporation. +Licensed under the MIT License. +*/ + +/* +Kernel implementation for blocking repeated n-grams. +*/ + +#include +#include +#include +#include +#include + +// Ban repeated ngrams of length = 'no_repeat_ngram_size' +__global__ void banRepeatedTokens( + long* __restrict__ tokens, + float* __restrict__ lprobs, + int max_predict_len, + int vocab_size, + int no_repeat_ngram_size) { + auto row = blockIdx.x; + auto col = threadIdx.x; + auto start = row * (max_predict_len) + col; + // Each thread compares ngram starting from + // thread index with final ngram starting from + // step - no_repeat_ngram_size +2 + auto check_start_pos = blockDim.x; + auto lprob_start = row * vocab_size; + bool is_banned = true; + extern __shared__ long tokens_shm[]; + tokens_shm[col] = tokens[start]; + if (col == blockDim.x - 1) { + for (int i = 1; i < no_repeat_ngram_size; i++) { + if (col + i < max_predict_len) { + tokens_shm[col + i] = tokens[start + i]; + } + } + } + __syncthreads(); + + for (int k = 0; k < no_repeat_ngram_size - 1; k++) { + if (tokens_shm[col + k] != tokens_shm[check_start_pos + k]) { + is_banned = false; + } + } + if (is_banned == true) { + auto token_to_be_banned = tokens_shm[col + no_repeat_ngram_size - 1]; + lprobs[lprob_start + token_to_be_banned] = -INFINITY; + } +} + +// Allocate blocks and threads based on +// batch size and sequence length and launch +// kernel +torch::Tensor ngram_repeat_block_cuda_forward( + const torch::Tensor tokens, + torch::Tensor lprobs, + int bsz, + int step, + int beam_size, + int no_repeat_ngram_size) { + int threads = step - no_repeat_ngram_size + 2; + if (threads <= 0) + return lprobs; + int max_predict_len = tokens.size(1); + int vocab_size = lprobs.size(1); + auto token_ptr = tokens.data_ptr(); + auto lprob_ptr = lprobs.data_ptr(); + int blocks = bsz * beam_size; + int shared_mem_size = (step + 1) * sizeof(long); + + // Launching N blocks where N is number of samples in a batch (beams*bsz) + // Launching T threads where T is number of previous ngrams in a sample + // Allocating shared mem per block for fastser access of input tokens since + // each token will be accessed N times to compare with current Ngram where + // N is Ngram size. + banRepeatedTokens<<>>( + token_ptr, lprob_ptr, max_predict_len, vocab_size, no_repeat_ngram_size); + return lprobs; +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/libbase/balanced_assignment.cpp b/PyTorch/NLP/new-Transformer/fairseq/clib/libbase/balanced_assignment.cpp new file mode 100644 index 00000000..1a5a1061 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/libbase/balanced_assignment.cpp @@ -0,0 +1,109 @@ +/** + * Copyright 2017-present, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the license found in the + * LICENSE file in the root directory of this source tree. + */ + +/* +C++ code for solving the linear assignment problem. +Based on the Auction Algorithm from +https://dspace.mit.edu/bitstream/handle/1721.1/3265/P-2108-26912652.pdf and the +implementation from: https://github.com/bkj/auction-lap Adapted to be more +efficient when each worker is looking for k jobs instead of 1. +*/ +#include +#include +using namespace torch::indexing; +torch::Tensor balanced_assignment(torch::Tensor job_and_worker_to_score) { + int max_iterations = 100; + torch::Tensor epsilon = + (job_and_worker_to_score.max() - job_and_worker_to_score.min()) / 50; + epsilon.clamp_min_(1e-04); + torch::Tensor worker_and_job_to_score = + job_and_worker_to_score.detach().transpose(0, 1).contiguous(); + int num_workers = worker_and_job_to_score.size(0); + int num_jobs = worker_and_job_to_score.size(1); + auto device = worker_and_job_to_score.device(); + int jobs_per_worker = num_jobs / num_workers; + torch::Tensor value = worker_and_job_to_score.clone(); + int counter = 0; + torch::Tensor max_value = worker_and_job_to_score.max(); + + torch::Tensor bid_indices; + torch::Tensor cost = worker_and_job_to_score.new_zeros({1, num_jobs}); + torch::Tensor bids = + worker_and_job_to_score.new_empty({num_workers, num_jobs}); + torch::Tensor bid_increments = + worker_and_job_to_score.new_empty({num_workers, jobs_per_worker}); + torch::Tensor top_values = + worker_and_job_to_score.new_empty({num_workers, jobs_per_worker + 1}); + torch::Tensor high_bids = worker_and_job_to_score.new_empty({num_jobs}); + + torch::Tensor top_index = top_values.to(torch::kLong); + torch::Tensor high_bidders = top_index.new_empty({num_jobs}); + torch::Tensor have_bids = high_bidders.to(torch::kBool); + torch::Tensor jobs_indices = + torch::arange({num_jobs}, torch::dtype(torch::kLong).device(device)); + torch::Tensor true_tensor = + torch::ones({1}, torch::dtype(torch::kBool).device(device)); + + while (true) { + bids.zero_(); + torch::topk_out(top_values, top_index, value, jobs_per_worker + 1, 1); + + // Each worker bids the difference in value between that job and the k+1th + // job + torch::sub_out( + bid_increments, + top_values.index({Slice(None, None), Slice(0, jobs_per_worker)}), + top_values.index({Slice(None, None), jobs_per_worker}).unsqueeze(1)); + + bid_increments.add_(epsilon); + bids.scatter_( + 1, + top_index.index({Slice(None, None), Slice(0, jobs_per_worker)}), + bid_increments); + + if (counter < max_iterations && counter > 0) { + // Put in a minimal bid to retain items from the last round if no-one else + // bids for them this round + bids.view(-1).index_put_({bid_indices}, epsilon); + } + + // Find the highest bidding worker per job + torch::max_out(high_bids, high_bidders, bids, 0); + torch::gt_out(have_bids, high_bids, 0); + + if (have_bids.all().item()) { + // All jobs were bid for + break; + } + + // Make popular items more expensive + cost.add_(high_bids); + torch::sub_out(value, worker_and_job_to_score, cost); + + bid_indices = ((high_bidders * num_jobs) + jobs_indices).index({have_bids}); + + if (counter < max_iterations) { + // Make sure that this item will be in the winning worker's top-k next + // time. + value.view(-1).index_put_({bid_indices}, max_value); + } else { + // Suboptimal approximation that converges quickly from current solution + value.view(-1).index_put_( + {bid_indices}, worker_and_job_to_score.view(-1).index({bid_indices})); + } + + counter += 1; + } + + return top_index.index({Slice(None, None), Slice(0, jobs_per_worker)}) + .reshape(-1); +} + +PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) { + m.def("balanced_assignment", &balanced_assignment, "Balanced Assignment"); +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/libbleu/libbleu.cpp b/PyTorch/NLP/new-Transformer/fairseq/clib/libbleu/libbleu.cpp new file mode 100644 index 00000000..939d9e11 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/libbleu/libbleu.cpp @@ -0,0 +1,157 @@ +/** + * Copyright 2017-present, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include +#include +#include +#include + +// NOLINTNEXTLINE +typedef struct { + size_t reflen; + size_t predlen; + size_t match1; + size_t count1; + size_t match2; + size_t count2; + size_t match3; + size_t count3; + size_t match4; + size_t count4; +} bleu_stat; + +// left trim (remove pad) +void bleu_ltrim(size_t* len, int** sent, int pad) { + size_t start = 0; + while (start < *len) { + if (*(*sent + start) != pad) { + break; + } + start++; + } + *sent += start; + *len -= start; +} + +// right trim remove (eos) +void bleu_rtrim(size_t* len, int** sent, int pad, int eos) { + size_t end = *len - 1; + while (end > 0) { + if (*(*sent + end) != eos && *(*sent + end) != pad) { + break; + } + end--; + } + *len = end + 1; +} + +// left and right trim +void bleu_trim(size_t* len, int** sent, int pad, int eos) { + bleu_ltrim(len, sent, pad); + bleu_rtrim(len, sent, pad, eos); +} + +size_t bleu_hash(int len, int* data) { + size_t h = 14695981039346656037ul; + size_t prime = 0x100000001b3; + char* b = (char*)data; + size_t blen = sizeof(int) * len; + + while (blen-- > 0) { + h ^= *b++; + h *= prime; + } + + return h; +} + +void bleu_addngram( + size_t* ntotal, + size_t* nmatch, + size_t n, + size_t reflen, + int* ref, + size_t predlen, + int* pred) { + if (predlen < n) { + return; + } + + predlen = predlen - n + 1; + (*ntotal) += predlen; + + if (reflen < n) { + return; + } + + reflen = reflen - n + 1; + + std::map count; + while (predlen > 0) { + size_t w = bleu_hash(n, pred++); + count[w]++; + predlen--; + } + + while (reflen > 0) { + size_t w = bleu_hash(n, ref++); + if (count[w] > 0) { + (*nmatch)++; + count[w] -= 1; + } + reflen--; + } +} + +extern "C" { + +#ifdef _WIN64 +__declspec(dllexport) +#endif + void bleu_zero_init(bleu_stat* stat) { + std::memset(stat, 0, sizeof(bleu_stat)); +} + +#ifdef _WIN64 +__declspec(dllexport) +#endif + void bleu_one_init(bleu_stat* stat) { + bleu_zero_init(stat); + stat->count1 = 0; + stat->count2 = 1; + stat->count3 = 1; + stat->count4 = 1; + stat->match1 = 0; + stat->match2 = 1; + stat->match3 = 1; + stat->match4 = 1; +} + +#ifdef _WIN64 +__declspec(dllexport) +#endif + void bleu_add( + bleu_stat* stat, + size_t reflen, + int* ref, + size_t predlen, + int* pred, + int pad, + int eos) { + + bleu_trim(&reflen, &ref, pad, eos); + bleu_trim(&predlen, &pred, pad, eos); + stat->reflen += reflen; + stat->predlen += predlen; + + bleu_addngram(&stat->count1, &stat->match1, 1, reflen, ref, predlen, pred); + bleu_addngram(&stat->count2, &stat->match2, 2, reflen, ref, predlen, pred); + bleu_addngram(&stat->count3, &stat->match3, 3, reflen, ref, predlen, pred); + bleu_addngram(&stat->count4, &stat->match4, 4, reflen, ref, predlen, pred); +} +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/libbleu/module.cpp b/PyTorch/NLP/new-Transformer/fairseq/clib/libbleu/module.cpp new file mode 100644 index 00000000..35288b31 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/libbleu/module.cpp @@ -0,0 +1,33 @@ +/** + * Copyright 2017-present, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include + +static PyMethodDef method_def[] = {{NULL, NULL, 0, NULL}}; // NOLINT + +static struct PyModuleDef module_def = { + PyModuleDef_HEAD_INIT, + "libbleu", /* name of module */ + // NOLINTNEXTLINE + NULL, /* module documentation, may be NULL */ + -1, /* size of per-interpreter state of the module, + or -1 if the module keeps state in global variables. */ + method_def}; // NOLINT + +#if PY_MAJOR_VERSION == 2 +PyMODINIT_FUNC init_libbleu() +#else +PyMODINIT_FUNC PyInit_libbleu() +#endif +{ + PyObject* m = PyModule_Create(&module_def); + if (!m) { + return NULL; + } + return m; +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/libnat/edit_dist.cpp b/PyTorch/NLP/new-Transformer/fairseq/clib/libnat/edit_dist.cpp new file mode 100644 index 00000000..9ffb6056 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/libnat/edit_dist.cpp @@ -0,0 +1,231 @@ +/** + * Copyright 2017-present, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include +#include +#include // @manual=//caffe2:torch_extension +#include +#include +#include +#include +#include +#include +#include +#include + +using namespace ::std; + +vector> edit_distance2_with_dp( + vector& x, + vector& y) { + uint32_t lx = x.size(); + uint32_t ly = y.size(); + vector> d(lx + 1, vector(ly + 1)); + for (uint32_t i = 0; i < lx + 1; i++) { + d[i][0] = i; + } + for (uint32_t j = 0; j < ly + 1; j++) { + d[0][j] = j; + } + for (uint32_t i = 1; i < lx + 1; i++) { + for (uint32_t j = 1; j < ly + 1; j++) { + d[i][j] = + min(min(d[i - 1][j], d[i][j - 1]) + 1, + d[i - 1][j - 1] + 2 * (x.at(i - 1) == y.at(j - 1) ? 0 : 1)); + } + } + return d; +} + +vector> edit_distance2_backtracking( + vector>& d, + vector& x, + vector& y, + uint32_t terminal_symbol) { + vector seq; + vector> edit_seqs(x.size() + 2, vector()); + /* + edit_seqs: + 0~x.size() cell is the insertion sequences + last cell is the delete sequence + */ + + if (x.size() == 0) { + edit_seqs.at(0) = y; + return edit_seqs; + } + + uint32_t i = d.size() - 1; + uint32_t j = d.at(0).size() - 1; + + while ((i >= 0) && (j >= 0)) { + if ((i == 0) && (j == 0)) { + break; + } + + if ((j > 0) && (d.at(i).at(j - 1) < d.at(i).at(j))) { + seq.push_back(1); // insert + seq.push_back(y.at(j - 1)); + j--; + } else if ((i > 0) && (d.at(i - 1).at(j) < d.at(i).at(j))) { + seq.push_back(2); // delete + seq.push_back(x.at(i - 1)); + i--; + } else { + seq.push_back(3); // keep + seq.push_back(x.at(i - 1)); + i--; + j--; + } + } + + uint32_t prev_op, op, s, word; + prev_op = 0, s = 0; + for (uint32_t k = 0; k < seq.size() / 2; k++) { + op = seq.at(seq.size() - 2 * k - 2); + word = seq.at(seq.size() - 2 * k - 1); + if (prev_op != 1) { + s++; + } + if (op == 1) // insert + { + edit_seqs.at(s - 1).push_back(word); + } else if (op == 2) // delete + { + edit_seqs.at(x.size() + 1).push_back(1); + } else { + edit_seqs.at(x.size() + 1).push_back(0); + } + + prev_op = op; + } + + for (uint32_t k = 0; k < edit_seqs.size(); k++) { + if (edit_seqs[k].size() == 0) { + edit_seqs[k].push_back(terminal_symbol); + } + } + return edit_seqs; +} + +vector> edit_distance2_backtracking_with_delete( + vector>& d, + vector& x, + vector& y, + uint32_t terminal_symbol, + uint32_t deletion_symbol) { + vector seq; + vector> edit_seqs(x.size() + 1, vector()); + /* + edit_seqs: + 0~x.size() cell is the insertion sequences + last cell is the delete sequence + */ + + if (x.size() == 0) { + edit_seqs.at(0) = y; + return edit_seqs; + } + + uint32_t i = d.size() - 1; + uint32_t j = d.at(0).size() - 1; + + while ((i >= 0) && (j >= 0)) { + if ((i == 0) && (j == 0)) { + break; + } + + if ((j > 0) && (d.at(i).at(j - 1) < d.at(i).at(j))) { + seq.push_back(1); // insert + seq.push_back(y.at(j - 1)); + j--; + } else if ((i > 0) && (d.at(i - 1).at(j) < d.at(i).at(j))) { + seq.push_back(2); // delete + seq.push_back(x.at(i - 1)); + i--; + } else { + seq.push_back(3); // keep + seq.push_back(x.at(i - 1)); + i--; + j--; + } + } + + uint32_t prev_op, op, s, word; + prev_op = 0, s = 0; + for (uint32_t k = 0; k < seq.size() / 2; k++) { + op = seq.at(seq.size() - 2 * k - 2); + word = seq.at(seq.size() - 2 * k - 1); + if (prev_op != 1) { + s++; + } + if (op == 1) // insert + { + edit_seqs.at(s - 1).push_back(word); + } else if (op == 2) // delete + { + edit_seqs.at(s - 1).push_back(deletion_symbol); + } + + prev_op = op; + } + + for (uint32_t k = 0; k < edit_seqs.size(); k++) { + if (edit_seqs.at(k).size() == 0) { + edit_seqs.at(k).push_back(terminal_symbol); + } + } + return edit_seqs; +} + +vector compute_ed2( + vector>& xs, + vector>& ys) { + vector distances(xs.size()); + for (uint32_t i = 0; i < xs.size(); i++) { + vector> d = edit_distance2_with_dp(xs.at(i), ys.at(i)); + distances.at(i) = d.at(xs.at(i).size()).at(ys.at(i).size()); + } + return distances; +} + +vector>> suggested_ed2_path( + vector>& xs, + vector>& ys, + uint32_t terminal_symbol) { + vector>> seq(xs.size()); + for (uint32_t i = 0; i < xs.size(); i++) { + vector> d = edit_distance2_with_dp(xs.at(i), ys.at(i)); + seq.at(i) = + edit_distance2_backtracking(d, xs.at(i), ys.at(i), terminal_symbol); + } + return seq; +} + +vector>> suggested_ed2_path_with_delete( + vector>& xs, + vector>& ys, + uint32_t terminal_symbol, + uint32_t deletion_symbol) { + vector>> seq(xs.size()); + for (uint32_t i = 0; i < xs.size(); i++) { + vector> d = edit_distance2_with_dp(xs.at(i), ys.at(i)); + seq.at(i) = edit_distance2_backtracking_with_delete( + d, xs.at(i), ys.at(i), terminal_symbol, deletion_symbol); + } + return seq; +} + +PYBIND11_MODULE(libnat, m) { + m.def("compute_ed2", &compute_ed2, "compute_ed2"); + m.def("suggested_ed2_path", &suggested_ed2_path, "suggested_ed2_path"); + m.def( + "suggested_ed2_path_with_delete", + &suggested_ed2_path_with_delete, + "suggested_ed2_path_with_delete"); +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/binding.cpp b/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/binding.cpp new file mode 100644 index 00000000..ced91c0d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/binding.cpp @@ -0,0 +1,67 @@ +/** + * Copyright 2017-present, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the license found in the + * LICENSE file in the root directory of this source tree. + */ + +/* + This code is partially adpoted from + https://github.com/1ytic/pytorch-edit-distance + */ + +#include +#include "edit_dist.h" + +#ifndef TORCH_CHECK +#define TORCH_CHECK AT_CHECK +#endif + +#define CHECK_CUDA(x) \ + TORCH_CHECK(x.type().is_cuda(), #x " must be a CUDA tensor") +#define CHECK_CONTIGUOUS(x) \ + TORCH_CHECK(x.is_contiguous(), #x " must be contiguous") +#define CHECK_INPUT(x) \ + CHECK_CUDA(x); \ + CHECK_CONTIGUOUS(x) + +torch::Tensor LevenshteinDistance( + torch::Tensor source, + torch::Tensor target, + torch::Tensor source_length, + torch::Tensor target_length) { + CHECK_INPUT(source); + CHECK_INPUT(target); + CHECK_INPUT(source_length); + CHECK_INPUT(target_length); + return LevenshteinDistanceCuda(source, target, source_length, target_length); +} + +torch::Tensor GenerateDeletionLabel( + torch::Tensor source, + torch::Tensor operations) { + CHECK_INPUT(source); + CHECK_INPUT(operations); + return GenerateDeletionLabelCuda(source, operations); +} + +std::pair GenerateInsertionLabel( + torch::Tensor target, + torch::Tensor operations) { + CHECK_INPUT(target); + CHECK_INPUT(operations); + return GenerateInsertionLabelCuda(target, operations); +} + +PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) { + m.def("levenshtein_distance", &LevenshteinDistance, "Levenshtein distance"); + m.def( + "generate_deletion_labels", + &GenerateDeletionLabel, + "Generate Deletion Label"); + m.def( + "generate_insertion_labels", + &GenerateInsertionLabel, + "Generate Insertion Label"); +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/edit_dist.cu b/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/edit_dist.cu new file mode 100644 index 00000000..96569d46 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/edit_dist.cu @@ -0,0 +1,344 @@ +/** + * Copyright 2017-present, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include "edit_dist.h" + +#include +#include +#include +#include +#include // std::pair + +template +__global__ void generate_deletion_label_kernel( + const scalar_t* __restrict__ source, + const size_t source_size, + const size_t operation_size, + int* __restrict__ operations, + int* __restrict__ labels) { + const int index = blockIdx.x; + const int offset = index * operation_size; + const int offset_label = index * source_size; + + for (int i = 0; i < source_size; i++) { + labels[offset_label + i] = 0; + } + + int k = 0; + for (int i = 0; i < operation_size; i++) { + if (operations[offset + i] == 0) { + break; + } else if (operations[offset + i] == 1) { + continue; + } else { + labels[offset_label + k] = 3 - operations[offset + i]; + k++; + } + } +} + +template +__global__ void generate_insertion_label_kernel( + const scalar_t* __restrict__ target, + const size_t target_size, + const size_t operation_size, + int* __restrict__ operations, + int* __restrict__ labels, + int* __restrict__ masks) { + const int index = blockIdx.x; + const int offset = index * operation_size; + const int offset_label = index * target_size; + + int k = 0; + int u = 0; + int m = 0; + + for (int i = 0; i < target_size; i++) { + labels[offset_label + i] = 0; + masks[offset_label + i] = 0; + } + + for (int i = 0; i < operation_size - 1; i++) { + if (operations[offset + i] == 0) { + break; + } else if (operations[offset + i] == 2) { + continue; + } else if (operations[offset + i] == 1) { + masks[offset_label + m] = 1; + u++; + m++; + } else { + labels[offset_label + k] = u; + masks[offset_label + m] = 0; + k++; + m++; + u = 0; + } + } +} + +template +__global__ void levenshtein_distance_kernel( + const scalar_t* __restrict__ source, + const scalar_t* __restrict__ target, + const int* __restrict__ source_length, + const int* __restrict__ target_length, + const size_t source_size, + const size_t target_size, + int* __restrict__ operations, + int* __restrict__ errors_curr) { + const int index = blockIdx.x; + const int offset = index * (source_size + target_size); + const int d = index * (source_size + 1) * (target_size + 1); + const int t = target_size + 1; + + auto err_idx = [d, t](int i, int j) { return d + i * t + j; }; + auto opt_idx = [offset](int k) { return offset + k; }; + + const int hyp_len = source_length[index]; + const int ref_len = target_length[index]; + const scalar_t* hyp_begin = source + index * source_size; + const scalar_t* ref_begin = target + index * target_size; + + // dynamic programming + for (int i = 0; i <= hyp_len; i++) { + errors_curr[err_idx(i, 0)] = i; + } + for (int j = 0; j <= ref_len; j++) { + errors_curr[err_idx(0, j)] = j; + } + for (int i = 1; i <= hyp_len; i++) { + for (int j = 1; j <= ref_len; j++) { + errors_curr[err_idx(i, j)] = min( + min(errors_curr[err_idx(i - 1, j)], errors_curr[err_idx(i, j - 1)]) + + 1, + errors_curr[err_idx(i - 1, j - 1)] + + 2 * (*(hyp_begin + i - 1) == *(ref_begin + j - 1) ? 0 : 1)); + } + } + + // back-tracing + int i = hyp_len; + int j = ref_len; + int o = hyp_len + ref_len; + + for (int k = 0; k < source_size + target_size; k++) { + operations[opt_idx(k)] = 0; + } + + while ((i >= 0) && (j >= 0)) { + if ((i == 0) && (j == 0)) { + break; + } + + if ((j > 0) && + (errors_curr[err_idx(i, j - 1)] < errors_curr[err_idx(i, j)])) { + o--; + operations[opt_idx(o)] = 1; + j--; // insertion + } else if ( + (i > 0) && + (errors_curr[err_idx(i - 1, j)] < errors_curr[err_idx(i, j)])) { + o--; + operations[opt_idx(o)] = 2; + i--; // deletion + } else { + o--; + operations[opt_idx(o)] = 3; + i--; + j--; // do nothing + } + } + + // moving to the left + for (int k = 0; k < hyp_len + ref_len; k++) { + if (k + o < hyp_len + ref_len) { + operations[opt_idx(k)] = operations[opt_idx(k + o)]; + } else { + operations[opt_idx(k)] = 0; // padding + } + } +} + +template +__global__ void faster_levenshtein_distance_kernel( + const scalar_t* __restrict__ source, + const scalar_t* __restrict__ target, + const int* __restrict__ source_length, + const int* __restrict__ target_length, + const size_t source_size, + const size_t target_size, + int* __restrict__ operations) { + extern __shared__ short errors[]; + auto errors_curr = errors; + + const int index = blockIdx.x; + const int offset = index * (source_size + target_size); + const int t = target_size + 1; + + auto err_idx = [t](int i, int j) { return i * t + j; }; + auto opt_idx = [offset](int k) { return offset + k; }; + + const int hyp_len = source_length[index]; + const int ref_len = target_length[index]; + const scalar_t* hyp_begin = source + index * source_size; + const scalar_t* ref_begin = target + index * target_size; + + // dynamic programming + for (int i = 0; i <= hyp_len; i++) { + errors_curr[err_idx(i, 0)] = i; + } + for (int j = 0; j <= ref_len; j++) { + errors_curr[err_idx(0, j)] = j; + } + for (int i = 1; i <= hyp_len; i++) { + for (int j = 1; j <= ref_len; j++) { + errors_curr[err_idx(i, j)] = min( + min(errors_curr[err_idx(i - 1, j)], errors_curr[err_idx(i, j - 1)]) + + 1, + errors_curr[err_idx(i - 1, j - 1)] + + 2 * (*(hyp_begin + i - 1) == *(ref_begin + j - 1) ? 0 : 1)); + } + } + + // back-tracing + int i = hyp_len; + int j = ref_len; + int o = hyp_len + ref_len; + + for (int k = 0; k < source_size + target_size; k++) { + operations[opt_idx(k)] = 0; + } + + while ((i >= 0) && (j >= 0)) { + if ((i == 0) && (j == 0)) { + break; + } + + if ((j > 0) && + (errors_curr[err_idx(i, j - 1)] < errors_curr[err_idx(i, j)])) { + o--; + operations[opt_idx(o)] = 1; + j--; // insertion + } else if ( + (i > 0) && + (errors_curr[err_idx(i - 1, j)] < errors_curr[err_idx(i, j)])) { + o--; + operations[opt_idx(o)] = 2; + i--; // deletion + } else { + o--; + operations[opt_idx(o)] = 3; + i--; + j--; // do nothing + } + } + + // moving to the left + for (int k = 0; k < hyp_len + ref_len; k++) { + if (k + o < hyp_len + ref_len) { + operations[opt_idx(k)] = operations[opt_idx(k + o)]; + } else { + operations[opt_idx(k)] = 0; // padding + } + } +} + +torch::Tensor GenerateDeletionLabelCuda( + torch::Tensor source, + torch::Tensor operations) { + const auto batch_size = source.size(0); + at::TensorOptions options(source.device()); + options = options.dtype(at::ScalarType::Int); + auto labels = torch::empty({batch_size, source.size(1)}, options); + auto stream = at::cuda::getCurrentCUDAStream(source.device().index()); + + AT_DISPATCH_ALL_TYPES(source.scalar_type(), "generate_deletion_labels", ([&] { + generate_deletion_label_kernel + <<>>( + source.data_ptr(), + source.size(1), + operations.size(1), + operations.data_ptr(), + labels.data_ptr()); + })); + + return labels; +} + +std::pair GenerateInsertionLabelCuda( + torch::Tensor target, + torch::Tensor operations) { + const auto batch_size = target.size(0); + at::TensorOptions options(target.device()); + options = options.dtype(at::ScalarType::Int); + auto labels = torch::empty({batch_size, target.size(1)}, options); + auto masks = torch::empty({batch_size, target.size(1)}, options); + auto stream = at::cuda::getCurrentCUDAStream(target.device().index()); + + AT_DISPATCH_ALL_TYPES( + target.scalar_type(), "generate_insertion_labels", ([&] { + generate_insertion_label_kernel<<>>( + target.data_ptr(), + target.size(1), + operations.size(1), + operations.data_ptr(), + labels.data_ptr(), + masks.data_ptr()); + })); + + return std::make_pair(labels, masks); +} + +torch::Tensor LevenshteinDistanceCuda( + torch::Tensor source, + torch::Tensor target, + torch::Tensor source_length, + torch::Tensor target_length) { + const auto batch_size = source.size(0); + const auto shared_size = + (source.size(1) + 1) * (target.size(1) + 1) * sizeof(short); + + at::TensorOptions options(source.device()); + options = options.dtype(at::ScalarType::Int); + auto operations = + torch::empty({batch_size, source.size(1) + target.size(1)}, options); + auto stream = at::cuda::getCurrentCUDAStream(source.device().index()); + + if (shared_size > 40000) { + auto distances = torch::empty( + {batch_size, (source.size(1) + 1) * (target.size(1) + 1)}, options); + AT_DISPATCH_ALL_TYPES(source.scalar_type(), "levenshtein_distance", ([&] { + levenshtein_distance_kernel + <<>>( + source.data_ptr(), + target.data_ptr(), + source_length.data_ptr(), + target_length.data_ptr(), + source.size(1), + target.size(1), + operations.data_ptr(), + distances.data_ptr()); + })); + } else { + AT_DISPATCH_ALL_TYPES( + source.scalar_type(), "faster_levenshtein_distance", ([&] { + faster_levenshtein_distance_kernel + <<>>( + source.data_ptr(), + target.data_ptr(), + source_length.data_ptr(), + target_length.data_ptr(), + source.size(1), + target.size(1), + operations.data_ptr()); + })); + } + + return operations; +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/edit_dist.h b/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/edit_dist.h new file mode 100644 index 00000000..5220c52f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/clib/libnat_cuda/edit_dist.h @@ -0,0 +1,25 @@ +/** + * Copyright 2017-present, Facebook, Inc. + * All rights reserved. + * + * This source code is licensed under the license found in the + * LICENSE file in the root directory of this source tree. + */ + +#pragma once + +#include + +torch::Tensor LevenshteinDistanceCuda( + torch::Tensor source, + torch::Tensor target, + torch::Tensor source_length, + torch::Tensor target_length); + +torch::Tensor GenerateDeletionLabelCuda( + torch::Tensor source, + torch::Tensor operations); + +std::pair GenerateInsertionLabelCuda( + torch::Tensor source, + torch::Tensor operations); diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/config/__init__.py new file mode 100644 index 00000000..62642369 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/__init__.py @@ -0,0 +1,4 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/config.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/config.yaml new file mode 100644 index 00000000..2ed7168c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/config.yaml @@ -0,0 +1,19 @@ +# @package _group_ + +hydra: + run: + dir: . + +defaults: + - _self_ + - task: null + - model: null + - criterion: cross_entropy + - optimizer: null + - lr_scheduler: fixed + - bpe: null + - tokenizer: null + - scoring: null + - generation: null + - common_eval: null + - eval_lm: null diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_baevski_gbw.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_baevski_gbw.yaml new file mode 100644 index 00000000..30b1a4f1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_baevski_gbw.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "relu" +dropout: 0.1 +attention_dropout: 0.1 +activation_dropout: 0.0 +relu_dropout: 0.0 +decoder_embed_dim: 512 +decoder_output_dim: 512 +decoder_input_dim: 512 +decoder_ffn_embed_dim: 4096 +decoder_layers: 12 +decoder_attention_heads: 16 +decoder_normalize_before: true +no_decoder_final_norm: true +adaptive_softmax_cutoff: null +adaptive_softmax_dropout: 0 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: false +adaptive_input_factor: 4 +adaptive_input_cutoff: null +tie_adaptive_weights: false +tie_adaptive_proj: false +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_baevski_wiki103.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_baevski_wiki103.yaml new file mode 100644 index 00000000..1154cfa6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_baevski_wiki103.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "relu" +dropout: 0.3 +attention_dropout: 0.1 +activation_dropout: 0.1 +relu_dropout: 0.1 +decoder_embed_dim: 1024 +decoder_output_dim: 1024 +decoder_input_dim: 1024 +decoder_ffn_embed_dim: 4096 +decoder_layers: 16 +decoder_attention_heads: 8 +decoder_normalize_before: true +no_decoder_final_norm: true +adaptive_softmax_cutoff: "20000,60000" +adaptive_softmax_dropout: 0.2 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: true +adaptive_input_factor: 4 +adaptive_input_cutoff: "20000,60000" +tie_adaptive_weights: true +tie_adaptive_proj: true +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_big.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_big.yaml new file mode 100644 index 00000000..30957531 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_big.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "relu" +dropout: 0.1 +attention_dropout: 0.0 +activation_dropout: 0.0 +relu_dropout: 0.0 +decoder_embed_dim: 1024 +decoder_output_dim: 1024 +decoder_input_dim: 1024 +decoder_ffn_embed_dim: 4096 +decoder_layers: 12 +decoder_attention_heads: 16 +decoder_normalize_before: true +no_decoder_final_norm: false +adaptive_softmax_cutoff: null +adaptive_softmax_dropout: 0 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: false +adaptive_input_factor: 4 +adaptive_input_cutoff: null +tie_adaptive_weights: false +tie_adaptive_proj: false +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gbw.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gbw.yaml new file mode 100644 index 00000000..30b1a4f1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gbw.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "relu" +dropout: 0.1 +attention_dropout: 0.1 +activation_dropout: 0.0 +relu_dropout: 0.0 +decoder_embed_dim: 512 +decoder_output_dim: 512 +decoder_input_dim: 512 +decoder_ffn_embed_dim: 4096 +decoder_layers: 12 +decoder_attention_heads: 16 +decoder_normalize_before: true +no_decoder_final_norm: true +adaptive_softmax_cutoff: null +adaptive_softmax_dropout: 0 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: false +adaptive_input_factor: 4 +adaptive_input_cutoff: null +tie_adaptive_weights: false +tie_adaptive_proj: false +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt.yaml new file mode 100644 index 00000000..2c6cb7be --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "gelu" +dropout: 0.1 +attention_dropout: 0.1 +activation_dropout: 0.0 +relu_dropout: 0.0 +decoder_embed_dim: 768 +decoder_output_dim: 768 +decoder_input_dim: 768 +decoder_ffn_embed_dim: 3072 +decoder_layers: 12 +decoder_attention_heads: 12 +decoder_normalize_before: true +no_decoder_final_norm: false +adaptive_softmax_cutoff: null +adaptive_softmax_dropout: 0 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: false +adaptive_input_factor: 4 +adaptive_input_cutoff: null +tie_adaptive_weights: false +tie_adaptive_proj: false +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_big.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_big.yaml new file mode 100644 index 00000000..a08769a1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_big.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "gelu" +dropout: 0.1 +attention_dropout: 0.1 +activation_dropout: 0.0 +relu_dropout: 0.0 +decoder_embed_dim: 1600 +decoder_output_dim: 1600 +decoder_input_dim: 1600 +decoder_ffn_embed_dim: 6400 +decoder_layers: 48 +decoder_attention_heads: 25 +decoder_normalize_before: true +no_decoder_final_norm: false +adaptive_softmax_cutoff: null +adaptive_softmax_dropout: 0 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: false +adaptive_input_factor: 4 +adaptive_input_cutoff: null +tie_adaptive_weights: false +tie_adaptive_proj: false +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_medium.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_medium.yaml new file mode 100644 index 00000000..64261d79 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_medium.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "gelu" +dropout: 0.1 +attention_dropout: 0.1 +activation_dropout: 0.0 +relu_dropout: 0.0 +decoder_embed_dim: 1280 +decoder_output_dim: 1280 +decoder_input_dim: 1280 +decoder_ffn_embed_dim: 5120 +decoder_layers: 36 +decoder_attention_heads: 20 +decoder_normalize_before: true +no_decoder_final_norm: false +adaptive_softmax_cutoff: null +adaptive_softmax_dropout: 0 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: false +adaptive_input_factor: 4 +adaptive_input_cutoff: null +tie_adaptive_weights: false +tie_adaptive_proj: false +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_small.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_small.yaml new file mode 100644 index 00000000..702e81f4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_gpt2_small.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "gelu" +dropout: 0.1 +attention_dropout: 0.1 +activation_dropout: 0.0 +relu_dropout: 0.0 +decoder_embed_dim: 1024 +decoder_output_dim: 1024 +decoder_input_dim: 1024 +decoder_ffn_embed_dim: 4096 +decoder_layers: 24 +decoder_attention_heads: 16 +decoder_normalize_before: true +no_decoder_final_norm: false +adaptive_softmax_cutoff: null +adaptive_softmax_dropout: 0 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: false +adaptive_input_factor: 4 +adaptive_input_cutoff: null +tie_adaptive_weights: false +tie_adaptive_proj: false +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_wiki103.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_wiki103.yaml new file mode 100644 index 00000000..1154cfa6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/transformer_lm/transformer_lm_wiki103.yaml @@ -0,0 +1,36 @@ +# @package _group_ +activation_fn: "relu" +dropout: 0.3 +attention_dropout: 0.1 +activation_dropout: 0.1 +relu_dropout: 0.1 +decoder_embed_dim: 1024 +decoder_output_dim: 1024 +decoder_input_dim: 1024 +decoder_ffn_embed_dim: 4096 +decoder_layers: 16 +decoder_attention_heads: 8 +decoder_normalize_before: true +no_decoder_final_norm: true +adaptive_softmax_cutoff: "20000,60000" +adaptive_softmax_dropout: 0.2 +adaptive_softmax_factor: 4 +no_token_positional_embeddings: false +share_decoder_input_output_embed: false +character_embeddings: false +character_filters: "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]" +character_embedding_dim: 4 +char_embedder_highway_layers: 2 +adaptive_input: true +adaptive_input_factor: 4 +adaptive_input_cutoff: "20000,60000" +tie_adaptive_weights: true +tie_adaptive_proj: true +decoder_learned_pos: false +decoder_layerdrop: 0 +decoder_layers_to_keep: null +layernorm_embedding: false +no_scale_embedding: false +quant_noise_pq: 0 +quant_noise_pq_block_size: 8 +quant_noise_scalar: 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec/vq_wav2vec_gumbel.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec/vq_wav2vec_gumbel.yaml new file mode 100644 index 00000000..ee1329bf --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec/vq_wav2vec_gumbel.yaml @@ -0,0 +1,5 @@ +# @package _group_ +activation: gelu +vq_type: gumbel +vq_depth: 2 +combine_groups: true diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec2/wav2vec2_base.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec2/wav2vec2_base.yaml new file mode 100644 index 00000000..ce65499b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec2/wav2vec2_base.yaml @@ -0,0 +1,8 @@ +# @package _group_ + +quantize_targets: true +final_dim: 256 +encoder_layerdrop: 0.05 +dropout_input: 0.1 +dropout_features: 0.1 +feature_grad_mult: 0.1 diff --git a/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec2/wav2vec2_large.yaml b/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec2/wav2vec2_large.yaml new file mode 100644 index 00000000..5846f752 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/config/model/wav2vec2/wav2vec2_large.yaml @@ -0,0 +1,20 @@ +# @package _group_ + +quantize_targets: true +extractor_mode: layer_norm +layer_norm_first: true +final_dim: 768 +latent_temp: [2.0,0.1,0.999995] +encoder_layerdrop: 0.0 +dropout_input: 0.0 +dropout_features: 0.0 +dropout: 0.0 +attention_dropout: 0.0 +conv_bias: true + +encoder_layers: 24 +encoder_embed_dim: 1024 +encoder_ffn_embed_dim: 4096 +encoder_attention_heads: 16 + +feature_grad_mult: 1.0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/__init__.py new file mode 100644 index 00000000..4dbf46a1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/__init__.py @@ -0,0 +1,36 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +import importlib +import os + +from fairseq import registry +from fairseq.criterions.fairseq_criterion import ( # noqa + FairseqCriterion, + LegacyFairseqCriterion, +) +from omegaconf import DictConfig + + +( + build_criterion_, + register_criterion, + CRITERION_REGISTRY, + CRITERION_DATACLASS_REGISTRY, +) = registry.setup_registry( + "--criterion", base_class=FairseqCriterion, default="cross_entropy" +) + + +def build_criterion(cfg: DictConfig, task): + return build_criterion_(cfg, task) + + +# automatically import any Python files in the criterions/ directory +for file in sorted(os.listdir(os.path.dirname(__file__))): + if file.endswith(".py") and not file.startswith("_"): + file_name = file[: file.find(".py")] + importlib.import_module("fairseq.criterions." + file_name) diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/adaptive_loss.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/adaptive_loss.py new file mode 100644 index 00000000..6209ceae --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/adaptive_loss.py @@ -0,0 +1,123 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass + +import torch.nn.functional as F +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.constants import DDP_BACKEND_CHOICES +from omegaconf import II + + +@dataclass +class AdaptiveLossConfig(FairseqDataclass): + sentence_avg: bool = II("optimization.sentence_avg") + ddp_backend: DDP_BACKEND_CHOICES = II("distributed_training.ddp_backend") + + +@register_criterion("adaptive_loss", dataclass=AdaptiveLossConfig) +class AdaptiveLoss(FairseqCriterion): + """This is an implementation of the loss function accompanying the adaptive softmax approximation for + graphical processing units (GPU), described in the paper "Efficient softmax approximation for GPUs" + (http://arxiv.org/abs/1609.04309).""" + + def __init__(self, task, sentence_avg): + super().__init__(task) + self.sentence_avg = sentence_avg + + @classmethod + def build_criterion(cls, cfg: AdaptiveLossConfig, task): + if cfg.ddp_backend in {"c10d", "pytorch_ddp"}: + raise Exception( + "AdaptiveLoss is not compatible with the PyTorch " + "version of DistributedDataParallel. Please use " + "`--ddp-backend=legacy_ddp` instead." + ) + return cls(task, cfg.sentence_avg) + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + + assert ( + hasattr(model.decoder, "adaptive_softmax") + and model.decoder.adaptive_softmax is not None + ) + adaptive_softmax = model.decoder.adaptive_softmax + + net_output = model(**sample["net_input"]) + orig_target = model.get_targets(sample, net_output) + + nsentences = orig_target.size(0) + orig_target = orig_target.view(-1) + + bsz = orig_target.size(0) + + logits, target = adaptive_softmax(net_output[0], orig_target) + assert len(target) == len(logits) + + loss = net_output[0].new(1 if reduce else bsz).zero_() + + for i in range(len(target)): + if target[i] is not None: + assert target[i].min() >= 0 and target[i].max() <= logits[i].size(1) + loss += F.cross_entropy( + logits[i], + target[i], + ignore_index=self.padding_idx, + reduction="sum" if reduce else "none", + ) + + orig = utils.strip_pad(orig_target, self.padding_idx) + ntokens = orig.numel() + sample_size = sample["target"].size(0) if self.sentence_avg else ntokens + logging_output = { + "loss": loss.data, + "ntokens": ntokens, + "nsentences": nsentences, + "sample_size": sample_size, + } + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = utils.item(sum(log.get("loss", 0) for log in logging_outputs)) + ntokens = utils.item(sum(log.get("ntokens", 0) for log in logging_outputs)) + sample_size = utils.item( + sum(log.get("sample_size", 0) for log in logging_outputs) + ) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + if sample_size != ntokens: + metrics.log_scalar( + "nll_loss", loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["nll_loss"].avg) + ) + else: + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["loss"].avg) + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/composite_loss.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/composite_loss.py new file mode 100644 index 00000000..98e835fa --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/composite_loss.py @@ -0,0 +1,100 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq import utils +from fairseq.criterions import LegacyFairseqCriterion, register_criterion +from torch import nn + + +@register_criterion("composite_loss") +class CompositeLoss(LegacyFairseqCriterion): + """This is a composite loss that, given a list of model outputs and a list of targets, + computes an average of losses for each output-target pair""" + + def __init__(self, args, task): + super().__init__(args, task) + self.underlying_criterion = args.underlying_criterion + + @staticmethod + def add_args(parser): + """Add criterion-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--underlying-criterion', type=str, metavar='VAL', required=True, + help='underlying criterion to use for the composite loss') + # fmt: on + + @staticmethod + def build_underlying_criterion(args, task): + saved_criterion = args.criterion + args.criterion = args.underlying_criterion + assert saved_criterion != args.underlying_criterion + underlying_criterion = task.build_criterion(args) + args.criterion = saved_criterion + return underlying_criterion + + @classmethod + def build_criterion(cls, args, task): + underlying_criterion = CompositeLoss.build_underlying_criterion(args, task) + + class FakeModel(nn.Module): + def __init__(self, model, net_out, target): + super().__init__() + self.model = model + self.net_out = net_out + self.target = target + + def forward(self, **unused): + return self.net_out + + def get_normalized_probs(self, net_output, log_probs, sample=None): + return self.model.get_normalized_probs( + net_output, log_probs, sample=sample + ) + + def get_targets(self, *unused): + return self.target + + @property + def decoder(self): + return self.model.decoder + + class _CompositeLoss(LegacyFairseqCriterion): + def __init__(self, args, task, underlying_criterion): + super().__init__(args, task) + self.underlying_criterion = underlying_criterion + + def forward(self, model, sample, reduce=True): + net_outputs = model(**sample["net_input"]) + targets = sample["target"] + + bsz = targets[0].size(0) + loss = net_outputs[0][0].new(1 if reduce else bsz).float().zero_() + + sample_size = 0 + logging_output = {} + for o, t in zip(net_outputs[0], targets): + m = FakeModel(model, (o, net_outputs[1]), t) + sample["target"] = t + l, ss, logging_output = self.underlying_criterion(m, sample, reduce) + loss += l + sample_size += ss + + loss.div_(len(targets)) + sample_size /= len(targets) + + logging_output["loss"] = utils.item(loss.data) if reduce else loss.data + return loss, sample_size, logging_output + + @staticmethod + def aggregate_logging_outputs(logging_outputs): + return underlying_criterion.__class__.aggregate_logging_outputs( + logging_outputs + ) + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + underlying_criterion.__class__.reduce_metrics(logging_outputs) + + return _CompositeLoss(args, task, underlying_criterion) diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/cross_entropy.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/cross_entropy.py new file mode 100644 index 00000000..fe461064 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/cross_entropy.py @@ -0,0 +1,90 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass + +import torch.nn.functional as F +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass +from omegaconf import II + + +@dataclass +class CrossEntropyCriterionConfig(FairseqDataclass): + sentence_avg: bool = II("optimization.sentence_avg") + + +@register_criterion("cross_entropy", dataclass=CrossEntropyCriterionConfig) +class CrossEntropyCriterion(FairseqCriterion): + def __init__(self, task, sentence_avg): + super().__init__(task) + self.sentence_avg = sentence_avg + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + net_output = model(**sample["net_input"]) + loss, _ = self.compute_loss(model, net_output, sample, reduce=reduce) + sample_size = ( + sample["target"].size(0) if self.sentence_avg else sample["ntokens"] + ) + logging_output = { + "loss": loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample["target"].size(0), + "sample_size": sample_size, + } + return loss, sample_size, logging_output + + def compute_loss(self, model, net_output, sample, reduce=True): + lprobs = model.get_normalized_probs(net_output, log_probs=True) + lprobs = lprobs.view(-1, lprobs.size(-1)) + target = model.get_targets(sample, net_output).view(-1) + loss = F.nll_loss( + lprobs, + target, + ignore_index=self.padding_idx, + reduction="sum" if reduce else "none", + ) + return loss, loss + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = sum(log.get("loss", 0) for log in logging_outputs) + ntokens = sum(log.get("ntokens", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + + # we divide by log(2) to convert the loss from base e to base 2 + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + if sample_size != ntokens: + metrics.log_scalar( + "nll_loss", loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["nll_loss"].avg) + ) + else: + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["loss"].avg) + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/ctc.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/ctc.py new file mode 100644 index 00000000..e966e47c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/ctc.py @@ -0,0 +1,295 @@ +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + +import math +from argparse import Namespace +from dataclasses import dataclass, field +from omegaconf import II +from typing import Optional + +import torch +import torch.nn.functional as F +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass +from fairseq.data.data_utils import post_process +from fairseq.tasks import FairseqTask +from fairseq.logging.meters import safe_round + + +@dataclass +class CtcCriterionConfig(FairseqDataclass): + zero_infinity: bool = field( + default=False, + metadata={"help": "zero inf loss when source length <= target length"}, + ) + sentence_avg: bool = II("optimization.sentence_avg") + post_process: str = field( + default="letter", + metadata={ + "help": "how to post process predictions into words. can be letter, " + "wordpiece, BPE symbols, etc. " + "See fairseq.data.data_utils.post_process() for full list of options" + }, + ) + wer_kenlm_model: Optional[str] = field( + default=None, + metadata={ + "help": "if this is provided, use kenlm to compute wer (along with other wer_* args)" + }, + ) + wer_lexicon: Optional[str] = field( + default=None, + metadata={"help": "lexicon to use with wer_kenlm_model"}, + ) + wer_lm_weight: float = field( + default=2.0, + metadata={"help": "lm weight to use with wer_kenlm_model"}, + ) + wer_word_score: float = field( + default=-1.0, + metadata={"help": "lm word score to use with wer_kenlm_model"}, + ) + + wer_args: Optional[str] = field( + default=None, + metadata={ + "help": "DEPRECATED: tuple of (wer_kenlm_model, wer_lexicon, wer_lm_weight, wer_word_score)" + }, + ) + + +@register_criterion("ctc", dataclass=CtcCriterionConfig) +class CtcCriterion(FairseqCriterion): + def __init__(self, cfg: CtcCriterionConfig, task: FairseqTask): + super().__init__(task) + self.blank_idx = ( + task.target_dictionary.index(task.blank_symbol) + if hasattr(task, "blank_symbol") + else 0 + ) + self.pad_idx = task.target_dictionary.pad() + self.eos_idx = task.target_dictionary.eos() + self.post_process = cfg.post_process + + if cfg.wer_args is not None: + ( + cfg.wer_kenlm_model, + cfg.wer_lexicon, + cfg.wer_lm_weight, + cfg.wer_word_score, + ) = eval(cfg.wer_args) + + if cfg.wer_kenlm_model is not None and cfg.wer_kenlm_model != "": + from examples.speech_recognition.w2l_decoder import W2lKenLMDecoder + + dec_args = Namespace() + dec_args.nbest = 1 + dec_args.criterion = "ctc" + dec_args.kenlm_model = cfg.wer_kenlm_model + dec_args.lexicon = cfg.wer_lexicon + dec_args.beam = 50 + dec_args.beam_size_token = min(50, len(task.target_dictionary)) + dec_args.beam_threshold = min(50, len(task.target_dictionary)) + dec_args.lm_weight = cfg.wer_lm_weight + dec_args.word_score = cfg.wer_word_score + dec_args.unk_weight = -math.inf + dec_args.sil_weight = 0 + + self.w2l_decoder = W2lKenLMDecoder(dec_args, task.target_dictionary) + else: + self.w2l_decoder = None + + self.zero_infinity = cfg.zero_infinity + self.sentence_avg = cfg.sentence_avg + + def forward(self, model, sample, reduce=True): + net_output = model(**sample["net_input"]) + lprobs = model.get_normalized_probs( + net_output, log_probs=True + ).contiguous() # (T, B, C) from the encoder + + if "src_lengths" in sample["net_input"]: + input_lengths = sample["net_input"]["src_lengths"] + else: + if net_output["padding_mask"] is not None: + non_padding_mask = ~net_output["padding_mask"] + input_lengths = non_padding_mask.long().sum(-1) + else: + input_lengths = lprobs.new_full( + (lprobs.size(1),), lprobs.size(0), dtype=torch.long + ) + + pad_mask = (sample["target"] != self.pad_idx) & ( + sample["target"] != self.eos_idx + ) + targets_flat = sample["target"].masked_select(pad_mask) + if "target_lengths" in sample: + target_lengths = sample["target_lengths"] + else: + target_lengths = pad_mask.sum(-1) + + with torch.backends.cudnn.flags(enabled=False): + loss = F.ctc_loss( + lprobs, + targets_flat, + input_lengths, + target_lengths, + blank=self.blank_idx, + reduction="sum", + zero_infinity=self.zero_infinity, + ) + + ntokens = ( + sample["ntokens"] if "ntokens" in sample else target_lengths.sum().item() + ) + + sample_size = sample["target"].size(0) if self.sentence_avg else ntokens + logging_output = { + "loss": utils.item(loss.data), # * sample['ntokens'], + "ntokens": ntokens, + "nsentences": sample["id"].numel(), + "sample_size": sample_size, + } + + if not model.training: + import editdistance + + with torch.no_grad(): + lprobs_t = lprobs.transpose(0, 1).float().contiguous().cpu() + + c_err = 0 + c_len = 0 + w_errs = 0 + w_len = 0 + wv_errs = 0 + for lp, t, inp_l in zip( + lprobs_t, + sample["target_label"] + if "target_label" in sample + else sample["target"], + input_lengths, + ): + lp = lp[:inp_l].unsqueeze(0) + + decoded = None + if self.w2l_decoder is not None: + decoded = self.w2l_decoder.decode(lp) + if len(decoded) < 1: + decoded = None + else: + decoded = decoded[0] + if len(decoded) < 1: + decoded = None + else: + decoded = decoded[0] + + p = (t != self.task.target_dictionary.pad()) & ( + t != self.task.target_dictionary.eos() + ) + targ = t[p] + targ_units = self.task.target_dictionary.string(targ) + targ_units_arr = targ.tolist() + + toks = lp.argmax(dim=-1).unique_consecutive() + pred_units_arr = toks[toks != self.blank_idx].tolist() + + c_err += editdistance.eval(pred_units_arr, targ_units_arr) + c_len += len(targ_units_arr) + + targ_words = post_process(targ_units, self.post_process).split() + + pred_units = self.task.target_dictionary.string(pred_units_arr) + pred_words_raw = post_process(pred_units, self.post_process).split() + + if decoded is not None and "words" in decoded: + pred_words = decoded["words"] + w_errs += editdistance.eval(pred_words, targ_words) + wv_errs += editdistance.eval(pred_words_raw, targ_words) + else: + dist = editdistance.eval(pred_words_raw, targ_words) + w_errs += dist + wv_errs += dist + + w_len += len(targ_words) + + logging_output["wv_errors"] = wv_errs + logging_output["w_errors"] = w_errs + logging_output["w_total"] = w_len + logging_output["c_errors"] = c_err + logging_output["c_total"] = c_len + + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + + loss_sum = utils.item(sum(log.get("loss", 0) for log in logging_outputs)) + ntokens = utils.item(sum(log.get("ntokens", 0) for log in logging_outputs)) + nsentences = utils.item( + sum(log.get("nsentences", 0) for log in logging_outputs) + ) + sample_size = utils.item( + sum(log.get("sample_size", 0) for log in logging_outputs) + ) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + metrics.log_scalar("ntokens", ntokens) + metrics.log_scalar("nsentences", nsentences) + if sample_size != ntokens: + metrics.log_scalar( + "nll_loss", loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + + c_errors = sum(log.get("c_errors", 0) for log in logging_outputs) + metrics.log_scalar("_c_errors", c_errors) + c_total = sum(log.get("c_total", 0) for log in logging_outputs) + metrics.log_scalar("_c_total", c_total) + w_errors = sum(log.get("w_errors", 0) for log in logging_outputs) + metrics.log_scalar("_w_errors", w_errors) + wv_errors = sum(log.get("wv_errors", 0) for log in logging_outputs) + metrics.log_scalar("_wv_errors", wv_errors) + w_total = sum(log.get("w_total", 0) for log in logging_outputs) + metrics.log_scalar("_w_total", w_total) + + if c_total > 0: + metrics.log_derived( + "uer", + lambda meters: safe_round( + meters["_c_errors"].sum * 100.0 / meters["_c_total"].sum, 3 + ) + if meters["_c_total"].sum > 0 + else float("nan"), + ) + if w_total > 0: + metrics.log_derived( + "wer", + lambda meters: safe_round( + meters["_w_errors"].sum * 100.0 / meters["_w_total"].sum, 3 + ) + if meters["_w_total"].sum > 0 + else float("nan"), + ) + metrics.log_derived( + "raw_wer", + lambda meters: safe_round( + meters["_wv_errors"].sum * 100.0 / meters["_w_total"].sum, 3 + ) + if meters["_w_total"].sum > 0 + else float("nan"), + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/fairseq_criterion.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/fairseq_criterion.py new file mode 100644 index 00000000..ff4beb02 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/fairseq_criterion.py @@ -0,0 +1,120 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import inspect +from typing import Any, Dict, List + +from fairseq import metrics, utils +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.utils import gen_parser_from_dataclass +from torch.nn.modules.loss import _Loss + + +class FairseqCriterion(_Loss): + def __init__(self, task): + super().__init__() + self.task = task + if hasattr(task, "target_dictionary"): + tgt_dict = task.target_dictionary + self.padding_idx = tgt_dict.pad() if tgt_dict is not None else -100 + + @classmethod + def add_args(cls, parser): + """Add criterion-specific arguments to the parser.""" + dc = getattr(cls, "__dataclass", None) + if dc is not None: + gen_parser_from_dataclass(parser, dc()) + + @classmethod + def build_criterion(cls, cfg: FairseqDataclass, task): + """Construct a criterion from command-line args.""" + # arguments in the __init__. + init_args = {} + for p in inspect.signature(cls).parameters.values(): + if ( + p.kind == p.POSITIONAL_ONLY + or p.kind == p.VAR_POSITIONAL + or p.kind == p.VAR_KEYWORD + ): + # we haven't implemented inference for these argument types, + # but PRs welcome :) + raise NotImplementedError("{} not supported".format(p.kind)) + + assert p.kind in {p.POSITIONAL_OR_KEYWORD, p.KEYWORD_ONLY} + + if p.name == "task": + init_args["task"] = task + elif p.name == "cfg": + init_args["cfg"] = cfg + elif hasattr(cfg, p.name): + init_args[p.name] = getattr(cfg, p.name) + elif p.default != p.empty: + pass # we'll use the default value + else: + raise NotImplementedError( + "Unable to infer Criterion arguments, please implement " + "{}.build_criterion".format(cls.__name__) + ) + return cls(**init_args) + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + raise NotImplementedError + + @staticmethod + def aggregate_logging_outputs( + logging_outputs: List[Dict[str, Any]] + ) -> Dict[str, Any]: + """Aggregate logging outputs from data parallel training.""" + utils.deprecation_warning( + "The aggregate_logging_outputs API is deprecated. " + "Please use the reduce_metrics API instead." + ) + raise NotImplementedError + + @classmethod + def reduce_metrics(cls, logging_outputs: List[Dict[str, Any]]) -> None: + """Aggregate logging outputs from data parallel training.""" + utils.deprecation_warning( + "Criterions should implement the reduce_metrics API. " + "Falling back to deprecated aggregate_logging_outputs API." + ) + agg_logging_outputs = cls.aggregate_logging_outputs(logging_outputs) + for k, v in agg_logging_outputs.items(): + if k in {"nsentences", "ntokens", "sample_size"}: + continue + metrics.log_scalar(k, v) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return False + + +class LegacyFairseqCriterion(FairseqCriterion): + def __init__(self, args, task): + super().__init__(task=task) + self.args = args + + utils.deprecation_warning( + "Criterions should take explicit arguments instead of an " + "argparse.Namespace object, please update your criterion by " + "extending FairseqCriterion instead of LegacyFairseqCriterion." + ) + + @classmethod + def build_criterion(cls, args, task): + """Construct a criterion from command-line args.""" + return cls(args, task) diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/fastspeech2_loss.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/fastspeech2_loss.py new file mode 100644 index 00000000..b317409e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/fastspeech2_loss.py @@ -0,0 +1,136 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + +from typing import List, Dict, Any +from dataclasses import dataclass, field + +import torch +import torch.nn.functional as F + +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass +from fairseq.data.data_utils import lengths_to_mask +from fairseq.models.fairseq_model import FairseqEncoderModel + + +@dataclass +class FastSpeech2CriterionConfig(FairseqDataclass): + ctc_weight: float = field(default=0.0, metadata={"help": "weight for CTC loss"}) + + +@register_criterion("fastspeech2", dataclass=FastSpeech2CriterionConfig) +class FastSpeech2Loss(FairseqCriterion): + def __init__(self, task, ctc_weight): + super().__init__(task) + self.ctc_weight = ctc_weight + + def forward(self, model: FairseqEncoderModel, sample, reduction="mean"): + src_tokens = sample["net_input"]["src_tokens"] + src_lens = sample["net_input"]["src_lengths"] + tgt_lens = sample["target_lengths"] + _feat_out, _feat_out_post, _, log_dur_out, pitch_out, energy_out = model( + src_tokens=src_tokens, + src_lengths=src_lens, + prev_output_tokens=sample["net_input"]["prev_output_tokens"], + incremental_state=None, + target_lengths=tgt_lens, + speaker=sample["speaker"], + durations=sample["durations"], + pitches=sample["pitches"], + energies=sample["energies"], + ) + + src_mask = lengths_to_mask(sample["net_input"]["src_lengths"]) + tgt_mask = lengths_to_mask(sample["target_lengths"]) + + pitches, energies = sample["pitches"], sample["energies"] + pitch_out, pitches = pitch_out[src_mask], pitches[src_mask] + energy_out, energies = energy_out[src_mask], energies[src_mask] + + feat_out, feat = _feat_out[tgt_mask], sample["target"][tgt_mask] + l1_loss = F.l1_loss(feat_out, feat, reduction=reduction) + if _feat_out_post is not None: + l1_loss += F.l1_loss(_feat_out_post[tgt_mask], feat, reduction=reduction) + + pitch_loss = F.mse_loss(pitch_out, pitches, reduction=reduction) + energy_loss = F.mse_loss(energy_out, energies, reduction=reduction) + + log_dur_out = log_dur_out[src_mask] + dur = sample["durations"].float() + dur = dur.half() if log_dur_out.type().endswith(".HalfTensor") else dur + log_dur = torch.log(dur + 1)[src_mask] + dur_loss = F.mse_loss(log_dur_out, log_dur, reduction=reduction) + + ctc_loss = torch.tensor(0.0).type_as(l1_loss) + if self.ctc_weight > 0.0: + lprobs = model.get_normalized_probs((_feat_out,), log_probs=True) + lprobs = lprobs.transpose(0, 1) # T x B x C + src_mask = lengths_to_mask(src_lens) + src_tokens_flat = src_tokens.masked_select(src_mask) + ctc_loss = ( + F.ctc_loss( + lprobs, + src_tokens_flat, + tgt_lens, + src_lens, + reduction=reduction, + zero_infinity=True, + ) + * self.ctc_weight + ) + + loss = l1_loss + dur_loss + pitch_loss + energy_loss + ctc_loss + + sample_size = sample["nsentences"] + logging_output = { + "loss": utils.item(loss.data), + "ntokens": sample["ntokens"], + "nsentences": sample["nsentences"], + "sample_size": sample_size, + "l1_loss": utils.item(l1_loss.data), + "dur_loss": utils.item(dur_loss.data), + "pitch_loss": utils.item(pitch_loss.data), + "energy_loss": utils.item(energy_loss.data), + "ctc_loss": utils.item(ctc_loss.data), + } + return loss, sample_size, logging_output + + @classmethod + def reduce_metrics(cls, logging_outputs: List[Dict[str, Any]]) -> None: + ns = [log.get("sample_size", 0) for log in logging_outputs] + ntot = sum(ns) + ws = [n / (ntot + 1e-8) for n in ns] + for key in [ + "loss", + "l1_loss", + "dur_loss", + "pitch_loss", + "energy_loss", + "ctc_loss", + ]: + vals = [log.get(key, 0) for log in logging_outputs] + val = sum(val * w for val, w in zip(vals, ws)) + metrics.log_scalar(key, val, ntot, round=3) + metrics.log_scalar("sample_size", ntot, len(logging_outputs)) + + # inference metrics + if "targ_frames" not in logging_outputs[0]: + return + n = sum(log.get("targ_frames", 0) for log in logging_outputs) + for key, new_key in [ + ("mcd_loss", "mcd_loss"), + ("pred_frames", "pred_ratio"), + ("nins", "ins_rate"), + ("ndel", "del_rate"), + ]: + val = sum(log.get(key, 0) for log in logging_outputs) + metrics.log_scalar(new_key, val / n, n, round=3) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + return False diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/hubert_criterion.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/hubert_criterion.py new file mode 100644 index 00000000..83b514ae --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/hubert_criterion.py @@ -0,0 +1,194 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +import re +from dataclasses import dataclass, field +from typing import List, Optional + +import torch +import torch.nn.functional as F +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class HubertCriterionConfig(FairseqDataclass): + pred_masked_weight: float = field( + default=1.0, + metadata={"help": "weight for predictive loss for masked frames"}, + ) + pred_nomask_weight: float = field( + default=0.0, + metadata={"help": "weight for predictive loss for unmasked frames"}, + ) + loss_weights: Optional[List[float]] = field( + default=None, + metadata={"help": "weights for additional loss terms (not first one)"}, + ) + log_keys: List[str] = field( + default_factory=lambda: [], + metadata={"help": "output keys to log"}, + ) + + +@register_criterion("hubert", dataclass=HubertCriterionConfig) +class HubertCriterion(FairseqCriterion): + def __init__( + self, + task, + pred_masked_weight, + pred_nomask_weight, + loss_weights=None, + log_keys=None, + ): + super().__init__(task) + self.pred_masked_weight = pred_masked_weight + self.pred_nomask_weight = pred_nomask_weight + self.loss_weights = loss_weights + self.log_keys = [] if log_keys is None else log_keys + + def forward(self, model, sample, reduce=True, log_pred=False): + """Compute the loss for the given sample. + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + net_output = model(target_list=sample["target_list"], **sample["net_input"]) + loss = 0.0 + sample_size = 0 + logging_output = {} + reduction = "sum" if reduce else "none" + + loss_m_list = [] + logp_m_list = model.get_logits(net_output, True) + targ_m_list = model.get_targets(net_output, True) + assert self.pred_masked_weight == 0 or len(logp_m_list) > 0 + for i, (logp_m, targ_m) in enumerate(zip(logp_m_list, targ_m_list)): + loss_m = F.cross_entropy(logp_m, targ_m, reduction=reduction) + loss_m_list.append(loss_m) + logging_output[f"loss_m_{i}"] = loss_m.detach().item() + if self.pred_masked_weight > 0: + loss += self.pred_masked_weight * sum(loss_m_list) + sample_size += targ_m_list[0].numel() + + loss_u_list = [] + logp_u_list = model.get_logits(net_output, False) + targ_u_list = model.get_targets(net_output, False) + assert self.pred_nomask_weight == 0 or len(logp_u_list) > 0 + for i, (logp_u, targ_u) in enumerate(zip(logp_u_list, targ_u_list)): + loss_u = F.cross_entropy(logp_u, targ_u, reduction=reduction) + loss_u_list.append(loss_u) + logging_output[f"loss_u_{i}"] = loss_u.detach().item() + if self.pred_nomask_weight > 0: + loss += self.pred_nomask_weight * sum(loss_u_list) + sample_size += targ_u_list[0].numel() + + if self.loss_weights is not None: + assert hasattr(model, "get_extra_losses") + extra_losses, names = model.get_extra_losses(net_output) + if torch.is_tensor(extra_losses): + extra_losses = [extra_losses] + names = [names] + if len(self.loss_weights) == 1 and len(extra_losses) != 1: + self.loss_weights = [self.loss_weights[0]] * len(extra_losses) + assert len(extra_losses) == len( + self.loss_weights + ), f"{len(extra_losses)}, {len(self.loss_weights)}" + for p, n, coef in zip(extra_losses, names, self.loss_weights): + if coef != 0 and p is not None: + p = coef * p.float() * sample_size + loss += p + logging_output[f"loss_{n}"] = p.item() + + logging_output = { + "loss": loss.item() if reduce else loss, + "ntokens": sample_size, + "nsentences": sample["id"].numel(), + "sample_size": sample_size, + **logging_output, + } + + for lk in self.log_keys: + if lk in net_output: + logging_output[lk] = float((net_output[lk])) + + def compute_correct(logits): + if logits.numel() == 0: + return 0, 0 + else: + assert logits.dim() > 1, logits.shape + max = logits.argmax(-1) == 0 + min = logits.argmin(-1) == 0 + both = max & min + corr = max.long().sum().item() - both.long().sum().item() + count = max.numel() + return corr, count + + with torch.no_grad(): + for i, logp_m in enumerate(logp_m_list): + corr_m, count_m = compute_correct(logp_m) + logging_output[f"correct_m_{i}"] = corr_m + logging_output[f"count_m_{i}"] = count_m + + for i, logp_u in enumerate(logp_u_list): + corr_u, count_u = compute_correct(logp_u) + logging_output[f"correct_u_{i}"] = corr_u + logging_output[f"count_u_{i}"] = count_u + + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training (copied from normal cross entropy).""" + loss_sum = sum(log.get("loss", 0) for log in logging_outputs) + ntokens = sum(log.get("ntokens", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + if sample_size != ntokens: + metrics.log_scalar( + "nll_loss", loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["nll_loss"].avg) + ) + else: + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["loss"].avg) + ) + + counts = {} + for lk in logging_outputs[0].keys(): + if lk.startswith("count_"): + val = sum(log[lk] for log in logging_outputs) + metrics.log_scalar(lk, val) + counts[lk] = val + + for lk in logging_outputs[0].keys(): + if lk.startswith("loss_"): + val = sum(log[lk] for log in logging_outputs) + metrics.log_scalar(lk, val / sample_size / math.log(2), round=3) + elif lk.startswith("correct_"): + val = sum(log[lk] for log in logging_outputs) + metrics.log_scalar(lk, val / counts[re.sub("correct", "count", lk)]) + + @staticmethod + def aggregate_logging_outputs(logging_outputs): + """Aggregate logging outputs from data parallel training.""" + raise NotImplementedError() + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return False diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy.py new file mode 100644 index 00000000..cb43be0c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy.py @@ -0,0 +1,167 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass, field + +import torch +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass +from omegaconf import II + + +@dataclass +class LabelSmoothedCrossEntropyCriterionConfig(FairseqDataclass): + label_smoothing: float = field( + default=0.0, + metadata={"help": "epsilon for label smoothing, 0 means no label smoothing"}, + ) + report_accuracy: bool = field( + default=False, + metadata={"help": "report accuracy metric"}, + ) + ignore_prefix_size: int = field( + default=0, + metadata={"help": "Ignore first N tokens"}, + ) + sentence_avg: bool = II("optimization.sentence_avg") + + +def label_smoothed_nll_loss(lprobs, target, epsilon, ignore_index=None, reduce=True): + if target.dim() == lprobs.dim() - 1: + target = target.unsqueeze(-1) + nll_loss = -lprobs.gather(dim=-1, index=target) + smooth_loss = -lprobs.sum(dim=-1, keepdim=True) + if ignore_index is not None: + pad_mask = target.eq(ignore_index) + nll_loss.masked_fill_(pad_mask, 0.0) + smooth_loss.masked_fill_(pad_mask, 0.0) + else: + nll_loss = nll_loss.squeeze(-1) + smooth_loss = smooth_loss.squeeze(-1) + if reduce: + nll_loss = nll_loss.sum() + smooth_loss = smooth_loss.sum() + eps_i = epsilon / (lprobs.size(-1) - 1) + loss = (1.0 - epsilon - eps_i) * nll_loss + eps_i * smooth_loss + return loss, nll_loss + + +@register_criterion( + "label_smoothed_cross_entropy", dataclass=LabelSmoothedCrossEntropyCriterionConfig +) +class LabelSmoothedCrossEntropyCriterion(FairseqCriterion): + def __init__( + self, + task, + sentence_avg, + label_smoothing, + ignore_prefix_size=0, + report_accuracy=False, + ): + super().__init__(task) + self.sentence_avg = sentence_avg + self.eps = label_smoothing + self.ignore_prefix_size = ignore_prefix_size + self.report_accuracy = report_accuracy + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + net_output = model(**sample["net_input"]) + loss, nll_loss = self.compute_loss(model, net_output, sample, reduce=reduce) + sample_size = ( + sample["target"].size(0) if self.sentence_avg else sample["ntokens"] + ) + logging_output = { + "loss": loss.data, + "nll_loss": nll_loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample["target"].size(0), + "sample_size": sample_size, + } + if self.report_accuracy: + n_correct, total = self.compute_accuracy(model, net_output, sample) + logging_output["n_correct"] = utils.item(n_correct.data) + logging_output["total"] = utils.item(total.data) + return loss, sample_size, logging_output + + def get_lprobs_and_target(self, model, net_output, sample): + lprobs = model.get_normalized_probs(net_output, log_probs=True) + target = model.get_targets(sample, net_output) + if self.ignore_prefix_size > 0: + # lprobs: B x T x C + lprobs = lprobs[:, self.ignore_prefix_size :, :].contiguous() + target = target[:, self.ignore_prefix_size :].contiguous() + return lprobs.view(-1, lprobs.size(-1)), target.view(-1) + + def compute_loss(self, model, net_output, sample, reduce=True): + lprobs, target = self.get_lprobs_and_target(model, net_output, sample) + loss, nll_loss = label_smoothed_nll_loss( + lprobs, + target, + self.eps, + ignore_index=self.padding_idx, + reduce=reduce, + ) + return loss, nll_loss + + def compute_accuracy(self, model, net_output, sample): + lprobs, target = self.get_lprobs_and_target(model, net_output, sample) + mask = target.ne(self.padding_idx) + n_correct = torch.sum( + lprobs.argmax(1).masked_select(mask).eq(target.masked_select(mask)) + ) + total = torch.sum(mask) + return n_correct, total + + @classmethod + def reduce_metrics(cls, logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = sum(log.get("loss", 0) for log in logging_outputs) + nll_loss_sum = sum(log.get("nll_loss", 0) for log in logging_outputs) + ntokens = sum(log.get("ntokens", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + metrics.log_scalar( + "nll_loss", nll_loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["nll_loss"].avg) + ) + + total = utils.item(sum(log.get("total", 0) for log in logging_outputs)) + if total > 0: + metrics.log_scalar("total", total) + n_correct = utils.item( + sum(log.get("n_correct", 0) for log in logging_outputs) + ) + metrics.log_scalar("n_correct", n_correct) + metrics.log_derived( + "accuracy", + lambda meters: round( + meters["n_correct"].sum * 100.0 / meters["total"].sum, 3 + ) + if meters["total"].sum > 0 + else float("nan"), + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_latency_augmented.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_latency_augmented.py new file mode 100644 index 00000000..d5fb390f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_latency_augmented.py @@ -0,0 +1,220 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +import torch +from fairseq import metrics, utils +from fairseq.criterions import register_criterion +from fairseq.criterions.label_smoothed_cross_entropy import ( + LabelSmoothedCrossEntropyCriterion, + LabelSmoothedCrossEntropyCriterionConfig, +) + +try: + from simuleval.metrics.latency import ( + AverageLagging, + AverageProportion, + DifferentiableAverageLagging, + ) + + LATENCY_METRICS = { + "average_lagging": AverageLagging, + "average_proportion": AverageProportion, + "differentiable_average_lagging": DifferentiableAverageLagging, + } +except ImportError: + LATENCY_METRICS = None + + +@dataclass +class LabelSmoothedCrossEntropyCriterionLatencyAugmentConfig( + LabelSmoothedCrossEntropyCriterionConfig +): + latency_avg_weight: float = field( + default=0.0, + metadata={"help": "weight fot average latency loss."}, + ) + latency_var_weight: float = field( + default=0.0, + metadata={"help": "weight fot variance latency loss."}, + ) + latency_avg_type: str = field( + default="differentiable_average_lagging", + metadata={"help": "latency type for average loss"}, + ) + latency_var_type: str = field( + default="variance_delay", + metadata={"help": "latency typ for variance loss"}, + ) + latency_gather_method: str = field( + default="weighted_average", + metadata={"help": "method to gather latency loss for all heads"}, + ) + latency_update_after: int = field( + default=0, + metadata={"help": "Add latency loss after certain steps"}, + ) + + +@register_criterion( + "latency_augmented_label_smoothed_cross_entropy", + dataclass=LabelSmoothedCrossEntropyCriterionLatencyAugmentConfig, +) +class LatencyAugmentedLabelSmoothedCrossEntropyCriterion( + LabelSmoothedCrossEntropyCriterion +): + def __init__( + self, + task, + sentence_avg, + label_smoothing, + ignore_prefix_size, + report_accuracy, + latency_avg_weight, + latency_var_weight, + latency_avg_type, + latency_var_type, + latency_gather_method, + latency_update_after, + ): + super().__init__( + task, sentence_avg, label_smoothing, ignore_prefix_size, report_accuracy + ) + assert LATENCY_METRICS is not None, "Please make sure SimulEval is installed." + + self.latency_avg_weight = latency_avg_weight + self.latency_var_weight = latency_var_weight + self.latency_avg_type = latency_avg_type + self.latency_var_type = latency_var_type + self.latency_gather_method = latency_gather_method + self.latency_update_after = latency_update_after + + def forward(self, model, sample, reduce=True): + net_output = model(**sample["net_input"]) + # 1. Compute cross entropy loss + loss, nll_loss = self.compute_loss(model, net_output, sample, reduce=reduce) + + # 2. Compute cross latency loss + latency_loss, expected_latency, expected_delays_var = self.compute_latency_loss( + model, sample, net_output + ) + + if self.latency_update_after > 0: + num_updates = getattr(model.decoder, "num_updates", None) + assert ( + num_updates is not None + ), "model.decoder doesn't have attribute 'num_updates'" + if num_updates <= self.latency_update_after: + latency_loss = 0 + + loss += latency_loss + + sample_size = ( + sample["target"].size(0) if self.sentence_avg else sample["ntokens"] + ) + + logging_output = { + "loss": loss.data, + "nll_loss": nll_loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample["target"].size(0), + "sample_size": sample_size, + "latency": expected_latency, + "delays_var": expected_delays_var, + "latency_loss": latency_loss, + } + + if self.report_accuracy: + n_correct, total = self.compute_accuracy(model, net_output, sample) + logging_output["n_correct"] = utils.item(n_correct.data) + logging_output["total"] = utils.item(total.data) + return loss, sample_size, logging_output + + def compute_latency_loss(self, model, sample, net_output): + assert ( + net_output[-1].encoder_padding_mask is None + or not net_output[-1].encoder_padding_mask[:, 0].any() + ), "Only right padding on source is supported." + # 1. Obtain the expected alignment + alpha_list = [item["alpha"] for item in net_output[1].attn_list] + num_layers = len(alpha_list) + bsz, num_heads, tgt_len, src_len = alpha_list[0].size() + + # bsz * num_layers * num_heads, tgt_len, src_len + alpha_all = torch.cat(alpha_list, dim=1).view(-1, tgt_len, src_len) + + # 2 compute expected delays + # bsz * num_heads * num_layers, tgt_len, src_len for MMA + steps = ( + torch.arange(1, 1 + src_len) + .unsqueeze(0) + .unsqueeze(1) + .expand_as(alpha_all) + .type_as(alpha_all) + ) + + expected_delays = torch.sum(steps * alpha_all, dim=-1) + + target_padding_mask = ( + model.get_targets(sample, net_output) + .eq(self.padding_idx) + .unsqueeze(1) + .expand(bsz, num_layers * num_heads, tgt_len) + .contiguous() + .view(-1, tgt_len) + ) + + src_lengths = ( + sample["net_input"]["src_lengths"] + .unsqueeze(1) + .expand(bsz, num_layers * num_heads) + .contiguous() + .view(-1) + ) + expected_latency = LATENCY_METRICS[self.latency_avg_type]( + expected_delays, src_lengths, None, target_padding_mask=target_padding_mask + ) + + # 2.1 average expected latency of heads + # bsz, num_layers * num_heads + expected_latency = expected_latency.view(bsz, -1) + if self.latency_gather_method == "average": + # bsz * tgt_len + expected_latency = expected_delays.mean(dim=1) + elif self.latency_gather_method == "weighted_average": + weights = torch.nn.functional.softmax(expected_latency, dim=1) + expected_latency = torch.sum(expected_latency * weights, dim=1) + elif self.latency_gather_method == "max": + expected_latency = expected_latency.max(dim=1)[0] + else: + raise NotImplementedError + + expected_latency = expected_latency.sum() + avg_loss = self.latency_avg_weight * expected_latency + + # 2.2 variance of expected delays + expected_delays_var = ( + expected_delays.view(bsz, -1, tgt_len).var(dim=1).mean(dim=1) + ) + expected_delays_var = expected_delays_var.sum() + var_loss = self.latency_avg_weight * expected_delays_var + + # 3. Final loss + latency_loss = avg_loss + var_loss + + return latency_loss, expected_latency, expected_delays_var + + @classmethod + def reduce_metrics(cls, logging_outputs) -> None: + super().reduce_metrics(logging_outputs) + latency = sum(log.get("latency", 0) for log in logging_outputs) + delays_var = sum(log.get("delays_var", 0) for log in logging_outputs) + latency_loss = sum(log.get("latency_loss", 0) for log in logging_outputs) + nsentences = sum(log.get("nsentences", 0) for log in logging_outputs) + metrics.log_scalar("latency", latency.float() / nsentences, nsentences, round=3) + metrics.log_scalar("delays_var", delays_var / nsentences, nsentences, round=3) + metrics.log_scalar( + "latency_loss", latency_loss / nsentences, nsentences, round=3 + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_with_alignment.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_with_alignment.py new file mode 100644 index 00000000..2ea37c16 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_with_alignment.py @@ -0,0 +1,130 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +from fairseq import metrics, utils +from fairseq.criterions import register_criterion + +from .label_smoothed_cross_entropy import ( + LabelSmoothedCrossEntropyCriterion, + LabelSmoothedCrossEntropyCriterionConfig, +) + +from dataclasses import dataclass, field + + +@dataclass +class LabelSmoothedCrossEntropyCriterionWithAlignmentConfig( + LabelSmoothedCrossEntropyCriterionConfig +): + alignment_lambda: float = field( + default=0.05, metadata={"help": "weight for the alignment loss"} + ) + + +@register_criterion( + "label_smoothed_cross_entropy_with_alignment", + dataclass=LabelSmoothedCrossEntropyCriterionWithAlignmentConfig, +) +class LabelSmoothedCrossEntropyCriterionWithAlignment( + LabelSmoothedCrossEntropyCriterion +): + def __init__(self, task, sentence_avg, label_smoothing, alignment_lambda): + super().__init__(task, sentence_avg, label_smoothing) + self.alignment_lambda = alignment_lambda + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + net_output = model(**sample["net_input"]) + loss, nll_loss = self.compute_loss(model, net_output, sample, reduce=reduce) + sample_size = ( + sample["target"].size(0) if self.sentence_avg else sample["ntokens"] + ) + logging_output = { + "loss": utils.item(loss.data) if reduce else loss.data, + "nll_loss": utils.item(nll_loss.data) if reduce else nll_loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample["target"].size(0), + "sample_size": sample_size, + } + + alignment_loss = None + + # Compute alignment loss only for training set and non dummy batches. + if "alignments" in sample and sample["alignments"] is not None: + alignment_loss = self.compute_alignment_loss(sample, net_output) + + if alignment_loss is not None: + logging_output["alignment_loss"] = utils.item(alignment_loss.data) + loss += self.alignment_lambda * alignment_loss + + return loss, sample_size, logging_output + + def compute_alignment_loss(self, sample, net_output): + attn_prob = net_output[1]["attn"][0] + bsz, tgt_sz, src_sz = attn_prob.shape + attn = attn_prob.view(bsz * tgt_sz, src_sz) + + align = sample["alignments"] + align_weights = sample["align_weights"].float() + + if len(align) > 0: + # Alignment loss computation. align (shape [:, 2]) contains the src-tgt index pairs corresponding to + # the alignments. align_weights (shape [:]) contains the 1 / frequency of a tgt index for normalizing. + loss = -( + (attn[align[:, 1][:, None], align[:, 0][:, None]]).log() + * align_weights[:, None] + ).sum() + else: + return None + + return loss + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = utils.item(sum(log.get("loss", 0) for log in logging_outputs)) + nll_loss_sum = utils.item( + sum(log.get("nll_loss", 0) for log in logging_outputs) + ) + alignment_loss_sum = utils.item( + sum(log.get("alignment_loss", 0) for log in logging_outputs) + ) + ntokens = utils.item(sum(log.get("ntokens", 0) for log in logging_outputs)) + sample_size = utils.item( + sum(log.get("sample_size", 0) for log in logging_outputs) + ) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + metrics.log_scalar( + "nll_loss", nll_loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + metrics.log_scalar( + "alignment_loss", + alignment_loss_sum / sample_size / math.log(2), + sample_size, + round=3, + ) + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["nll_loss"].avg) + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_with_ctc.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_with_ctc.py new file mode 100644 index 00000000..e98e0f7d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/label_smoothed_cross_entropy_with_ctc.py @@ -0,0 +1,96 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass, field + +import torch +import torch.nn.functional as F + +from fairseq import metrics, utils +from fairseq.criterions import register_criterion +from fairseq.criterions.label_smoothed_cross_entropy import ( + LabelSmoothedCrossEntropyCriterion, + LabelSmoothedCrossEntropyCriterionConfig, +) +from fairseq.data.data_utils import lengths_to_mask + + +@dataclass +class LabelSmoothedCrossEntropyWithCtcCriterionConfig( + LabelSmoothedCrossEntropyCriterionConfig +): + ctc_weight: float = field(default=1.0, metadata={"help": "weight for CTC loss"}) + + +@register_criterion( + "label_smoothed_cross_entropy_with_ctc", + dataclass=LabelSmoothedCrossEntropyWithCtcCriterionConfig, +) +class LabelSmoothedCrossEntropyWithCtcCriterion(LabelSmoothedCrossEntropyCriterion): + def __init__( + self, + task, + sentence_avg, + label_smoothing, + ignore_prefix_size, + report_accuracy, + ctc_weight, + ): + super().__init__( + task, sentence_avg, label_smoothing, ignore_prefix_size, report_accuracy + ) + self.ctc_weight = ctc_weight + + def forward(self, model, sample, reduce=True): + net_output = model(**sample["net_input"]) + loss, nll_loss = self.compute_loss(model, net_output, sample, reduce=reduce) + + ctc_loss = torch.tensor(0.0).type_as(loss) + if self.ctc_weight > 0.0: + ctc_lprobs, ctc_lens = model.get_ctc_output(net_output, sample) + ctc_tgt, ctc_tgt_lens = model.get_ctc_target(sample) + ctc_tgt_mask = lengths_to_mask(ctc_tgt_lens) + ctc_tgt_flat = ctc_tgt.masked_select(ctc_tgt_mask) + reduction = "sum" if reduce else "none" + ctc_loss = ( + F.ctc_loss( + ctc_lprobs, + ctc_tgt_flat, + ctc_lens, + ctc_tgt_lens, + reduction=reduction, + zero_infinity=True, + ) + * self.ctc_weight + ) + loss += ctc_loss + + sample_size = ( + sample["target"].size(0) if self.sentence_avg else sample["ntokens"] + ) + logging_output = { + "loss": utils.item(loss.data), + "nll_loss": utils.item(nll_loss.data), + "ctc_loss": utils.item(ctc_loss.data), + "ntokens": sample["ntokens"], + "nsentences": sample["target"].size(0), + "sample_size": sample_size, + } + if self.report_accuracy: + n_correct, total = self.compute_accuracy(model, net_output, sample) + logging_output["n_correct"] = utils.item(n_correct.data) + logging_output["total"] = utils.item(total.data) + return loss, sample_size, logging_output + + @classmethod + def reduce_metrics(cls, logging_outputs) -> None: + super().reduce_metrics(logging_outputs) + loss_sum = sum(log.get("ctc_loss", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + + metrics.log_scalar( + "ctc_loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/legacy_masked_lm.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/legacy_masked_lm.py new file mode 100644 index 00000000..c70608c5 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/legacy_masked_lm.py @@ -0,0 +1,177 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch +import torch.nn.functional as F +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion + + +def compute_cross_entropy_loss(logits, targets, ignore_index=-100): + """ + Function to compute the cross entropy loss. The default value of + ignore_index is the same as the default value for F.cross_entropy in + pytorch. + """ + assert logits.size(0) == targets.size( + -1 + ), "Logits and Targets tensor shapes don't match up" + + loss = F.nll_loss( + F.log_softmax(logits, -1, dtype=torch.float32), + targets, + reduction="sum", + ignore_index=ignore_index, + ) + return loss + + +@register_criterion("legacy_masked_lm_loss") +class LegacyMaskedLmLoss(FairseqCriterion): + """ + Implementation for the loss used in masked language model (MLM) training. + This optionally also computes the next sentence prediction (NSP) loss and + adds it to the overall loss based on the specified args. There are three + cases to consider: + 1) Generic MLM training without NSP loss. In this case sentence_targets + and sentence_logits are both None. + 2) BERT training without NSP loss. In this case sentence_targets is + not None but sentence_logits is None and we should not be computing + a sentence level loss. + 3) BERT training with NSP loss. In this case both sentence_targets and + sentence_logits are not None and we should be computing a sentence + level loss. The weight of the sentence level loss is specified as + an argument. + """ + + def __init__(self, task, masked_lm_only, nsp_loss_weight): + super().__init__(task) + self.masked_lm_only = masked_lm_only + self.nsp_loss_weight = nsp_loss_weight + + @staticmethod + def add_args(parser): + """Args for MaskedLM Loss""" + # Default for masked_lm_only is False so as to not break BERT training + parser.add_argument( + "--masked-lm-only", + default=False, + action="store_true", + help="compute MLM loss only", + ) + parser.add_argument( + "--nsp-loss-weight", + default=1.0, + type=float, + help="weight for next sentence prediction" " loss (default 1)", + ) + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + lm_logits, output_metadata = model(**sample["net_input"]) + + # reshape lm_logits from (N,T,C) to (N*T,C) + lm_logits = lm_logits.view(-1, lm_logits.size(-1)) + lm_targets = sample["lm_target"].view(-1) + lm_loss = compute_cross_entropy_loss(lm_logits, lm_targets, self.padding_idx) + + # compute the number of tokens for which loss is computed. This is used + # to normalize the loss + ntokens = utils.strip_pad(lm_targets, self.padding_idx).numel() + loss = lm_loss / ntokens + nsentences = sample["nsentences"] + # nsentences = 0 + + # Compute sentence loss if masked_lm_only is False + sentence_loss = None + if not self.masked_lm_only: + sentence_logits = output_metadata["sentence_logits"] + sentence_targets = sample["sentence_target"].view(-1) + # This needs to be recomputed due to some differences between + # TokenBlock and BlockPair dataset. This can be resolved with a + # refactor of BERTModel which we will do in the future. + # TODO: Remove this after refactor of BERTModel + nsentences = sentence_targets.size(0) + + # Check for logits being none which can happen when remove_heads + # is set to true in the BERT model. Ideally we should set + # masked_lm_only to true in this case, but that requires some + # refactor in the BERT model. + if sentence_logits is not None: + sentence_loss = compute_cross_entropy_loss( + sentence_logits, sentence_targets + ) + + loss += self.nsp_loss_weight * (sentence_loss / nsentences) + + # NOTE: as we are summing up per token mlm loss and per sentence nsp loss + # we don't need to use sample_size as denominator for the gradient + # here sample_size is just used for logging + sample_size = 1 + logging_output = { + "loss": utils.item(loss.data) if reduce else loss.data, + "lm_loss": utils.item(lm_loss.data) if reduce else lm_loss.data, + # sentence loss is not always computed + "sentence_loss": ( + (utils.item(sentence_loss.data) if reduce else sentence_loss.data) + if sentence_loss is not None + else 0.0 + ), + "ntokens": ntokens, + "nsentences": nsentences, + "sample_size": sample_size, + } + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + lm_loss_sum = sum(log.get("lm_loss", 0) for log in logging_outputs) + sentence_loss_sum = sum(log.get("sentence_loss", 0) for log in logging_outputs) + ntokens = sum(log.get("ntokens", 0) for log in logging_outputs) + nsentences = sum(log.get("nsentences", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + agg_loss = sum(log.get("loss", 0) for log in logging_outputs) + + metrics.log_scalar( + "loss", + agg_loss / sample_size / math.log(2) if sample_size > 0 else 0.0, + sample_size, + round=3, + ) + metrics.log_scalar( + "lm_loss", + lm_loss_sum / ntokens / math.log(2) if ntokens > 0 else 0.0, + ntokens, + round=3, + ) + metrics.log_scalar( + "sentence_loss", + sentence_loss_sum / nsentences / math.log(2) if nsentences > 0 else 0.0, + nsentences, + round=3, + ) + metrics.log_scalar( + "nll_loss", + lm_loss_sum / ntokens / math.log(2) if ntokens > 0 else 0.0, + ntokens, + round=3, + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/masked_lm.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/masked_lm.py new file mode 100644 index 00000000..279458f3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/masked_lm.py @@ -0,0 +1,98 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass +import math +from omegaconf import II + +import torch +from fairseq import metrics, modules, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class MaskedLmConfig(FairseqDataclass): + tpu: bool = II("common.tpu") + + +@register_criterion("masked_lm", dataclass=MaskedLmConfig) +class MaskedLmLoss(FairseqCriterion): + """ + Implementation for the loss used in masked language model (MLM) training. + """ + + def __init__(self, cfg: MaskedLmConfig, task): + super().__init__(task) + self.tpu = cfg.tpu + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + masked_tokens = sample["target"].ne(self.padding_idx) + sample_size = masked_tokens.int().sum() + + # Rare: when all tokens are masked, project all tokens. + # We use torch.where to avoid device-to-host transfers, + # except on CPU where torch.where is not well supported + # (see github.com/pytorch/pytorch/issues/26247). + if self.tpu: + masked_tokens = None # always project all tokens on TPU + elif masked_tokens.device == torch.device("cpu"): + if not masked_tokens.any(): + masked_tokens = None + else: + masked_tokens = torch.where( + masked_tokens.any(), + masked_tokens, + masked_tokens.new([True]), + ) + + logits = model(**sample["net_input"], masked_tokens=masked_tokens)[0] + targets = model.get_targets(sample, [logits]) + if masked_tokens is not None: + targets = targets[masked_tokens] + + loss = modules.cross_entropy( + logits.view(-1, logits.size(-1)), + targets.view(-1), + reduction="sum", + ignore_index=self.padding_idx, + ) + + logging_output = { + "loss": loss if self.tpu else loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample["nsentences"], + "sample_size": sample_size, + } + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = sum(log.get("loss", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["loss"].avg) + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/model_criterion.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/model_criterion.py new file mode 100644 index 00000000..f9a810d8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/model_criterion.py @@ -0,0 +1,155 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from dataclasses import dataclass, field +from typing import Dict, List + +import torch + +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass + + +logger = logging.getLogger(__name__) + + +@dataclass +class ModelCriterionConfig(FairseqDataclass): + loss_weights: Dict[str, float] = field( + default_factory=dict, + metadata={"help": "weights for the loss terms"}, + ) + log_keys: List[str] = field( + default_factory=list, + metadata={"help": "additional output keys to log"}, + ) + + +@register_criterion("model", dataclass=ModelCriterionConfig) +class ModelCriterion(FairseqCriterion): + """ + This criterion relies on the model to supply losses. + The losses should be a dictionary of name -> scalar returned by + the model either by including it in the net_output dict or by + implementing a get_losses(net_output, sample) method. The final loss is + a scaled sum of all losses according to weights in loss_weights. + If no weights are provided, then all losses are scaled by 1.0. + + The losses will be automatically logged. Additional keys from + net_output dict can be logged via the log_keys parameter. + """ + + def __init__(self, task, loss_weights=None, log_keys=None): + super().__init__(task) + self.loss_weights = loss_weights + self.log_keys = log_keys + + def forward(self, model, sample, reduce=True): + net_output = model(**sample["net_input"]) + + scaled_losses = {} + + if hasattr(model, "get_losses"): + losses = model.get_losses(net_output, sample) + elif isinstance(net_output, dict) and "losses" in net_output: + losses = net_output["losses"] + else: + raise Exception("Could not retrieve losses") + + for lk, p in losses.items(): + try: + coef = 1.0 if len(self.loss_weights) == 0 else self.loss_weights[lk] + except KeyError: + logger.error( + f"weight for loss {lk} is not in loss_weights ({self.loss_weights})" + ) + raise + if coef != 0 and p is not None: + scaled_losses[lk] = coef * p.float() + + loss = sum(scaled_losses.values()) + + if "sample_size" in net_output: + sample_size = net_output["sample_size"] + else: + sample_size = loss.numel() + + if reduce and loss.numel() > 1: + loss = loss.sum() + + logging_output = { + "loss": loss.data, + "ntokens": sample_size, + "nsentences": sample["id"].numel(), + "sample_size": sample_size, + "_world_size": 1, + } + + for lk in self.log_keys: + if lk in net_output and net_output[lk] is not None: + if not torch.is_tensor(net_output[lk]) or net_output[lk].numel() == 1: + logging_output[lk] = float(net_output[lk]) + else: + for i, v in enumerate(net_output[lk]): + logging_output[f"{lk}_{i}"] = float(v) + + if len(scaled_losses) > 1: + for lk, l in scaled_losses.items(): + if l.numel() > 1: + l = l.sum() + logging_output[f"loss_{lk}"] = l.item() + + if "logs" in net_output: + for lgw in net_output["logs"]: + logging_output[lgw] = net_output["logs"][lgw] + + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = utils.item(sum(log.get("loss", 0) for log in logging_outputs)) + ntokens = utils.item(sum(log.get("ntokens", 0) for log in logging_outputs)) + nsentences = utils.item( + sum(log.get("nsentences", 0) for log in logging_outputs) + ) + sample_size = utils.item( + sum(log.get("sample_size", 0) for log in logging_outputs) + ) + + metrics.log_scalar("loss", loss_sum / sample_size, sample_size, round=3) + metrics.log_scalar("ntokens", ntokens) + metrics.log_scalar("nsentences", nsentences) + + builtin_keys = { + "loss", + "ntokens", + "nsentences", + "sample_size", + "_world_size", + } + + world_size = utils.item( + sum(log.get("_world_size", 0) for log in logging_outputs) + ) + + for k in logging_outputs[0]: + if k not in builtin_keys: + val = sum(log.get(k, 0) for log in logging_outputs) + if k.startswith("loss_"): + metrics.log_scalar(k, val / sample_size, sample_size, round=3) + else: + metrics.log_scalar(k, val / world_size, round=3) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/nat_loss.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/nat_loss.py new file mode 100644 index 00000000..7dac32fb --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/nat_loss.py @@ -0,0 +1,180 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch +import torch.nn.functional as F +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass +from torch import Tensor + +from dataclasses import dataclass, field + + +@dataclass +class LabelSmoothedDualImitationCriterionConfig(FairseqDataclass): + label_smoothing: float = field( + default=0.0, + metadata={"help": "epsilon for label smoothing, 0 means no label smoothing"}, + ) + + +@register_criterion("nat_loss", dataclass=LabelSmoothedDualImitationCriterionConfig) +class LabelSmoothedDualImitationCriterion(FairseqCriterion): + def __init__(self, task, label_smoothing): + super().__init__(task) + self.label_smoothing = label_smoothing + + def _compute_loss( + self, outputs, targets, masks=None, label_smoothing=0.0, name="loss", factor=1.0 + ): + """ + outputs: batch x len x d_model + targets: batch x len + masks: batch x len + + policy_logprob: if there is some policy + depends on the likelihood score as rewards. + """ + + def mean_ds(x: Tensor, dim=None) -> Tensor: + return ( + x.float().mean().type_as(x) + if dim is None + else x.float().mean(dim).type_as(x) + ) + + if masks is not None: + outputs, targets = outputs[masks], targets[masks] + + if masks is not None and not masks.any(): + nll_loss = torch.tensor(0) + loss = nll_loss + else: + logits = F.log_softmax(outputs, dim=-1) + if targets.dim() == 1: + losses = F.nll_loss(logits, targets.to(logits.device), reduction="none") + + else: # soft-labels + losses = F.kl_div(logits, targets.to(logits.device), reduction="none") + losses = losses.sum(-1) + + nll_loss = mean_ds(losses) + if label_smoothing > 0: + loss = ( + nll_loss * (1 - label_smoothing) - mean_ds(logits) * label_smoothing + ) + else: + loss = nll_loss + + loss = loss * factor + return {"name": name, "loss": loss, "nll_loss": nll_loss, "factor": factor} + + def _custom_loss(self, loss, name="loss", factor=1.0): + return {"name": name, "loss": loss, "factor": factor} + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + nsentences, ntokens = sample["nsentences"], sample["ntokens"] + + # B x T + src_tokens, src_lengths = ( + sample["net_input"]["src_tokens"], + sample["net_input"]["src_lengths"], + ) + tgt_tokens, prev_output_tokens = sample["target"], sample["prev_target"] + + outputs = model(src_tokens, src_lengths, prev_output_tokens, tgt_tokens) + losses, nll_loss = [], [] + + for obj in outputs: + if outputs[obj].get("loss", None) is None: + _losses = self._compute_loss( + outputs[obj].get("out"), + outputs[obj].get("tgt"), + outputs[obj].get("mask", None), + outputs[obj].get("ls", 0.0), + name=obj + "-loss", + factor=outputs[obj].get("factor", 1.0), + ) + else: + _losses = self._custom_loss( + outputs[obj].get("loss"), + name=obj + "-loss", + factor=outputs[obj].get("factor", 1.0), + ) + + losses += [_losses] + if outputs[obj].get("nll_loss", False): + nll_loss += [_losses.get("nll_loss", 0.0)] + + loss = sum(l["loss"] for l in losses) + nll_loss = sum(l for l in nll_loss) if len(nll_loss) > 0 else loss.new_tensor(0) + + # NOTE: + # we don't need to use sample_size as denominator for the gradient + # here sample_size is just used for logging + sample_size = 1 + logging_output = { + "loss": loss.data, + "nll_loss": nll_loss.data, + "ntokens": ntokens, + "nsentences": nsentences, + "sample_size": sample_size, + } + + for l in losses: + logging_output[l["name"]] = ( + utils.item(l["loss"].data / l["factor"]) + if reduce + else l[["loss"]].data / l["factor"] + ) + + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + sample_size = utils.item( + sum(log.get("sample_size", 0) for log in logging_outputs) + ) + loss = utils.item(sum(log.get("loss", 0) for log in logging_outputs)) + nll_loss = utils.item(sum(log.get("nll_loss", 0) for log in logging_outputs)) + + metrics.log_scalar( + "loss", loss / sample_size / math.log(2), sample_size, round=3 + ) + metrics.log_scalar( + "nll_loss", nll_loss / sample_size / math.log(2), sample_size, round=3 + ) + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["loss"].avg) + ) + + for key in logging_outputs[0]: + if key[-5:] == "-loss": + val = sum(log.get(key, 0) for log in logging_outputs) + metrics.log_scalar( + key[:-5], + val / sample_size / math.log(2) if sample_size > 0 else 0.0, + sample_size, + round=3, + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_prediction.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_prediction.py new file mode 100644 index 00000000..b402d760 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_prediction.py @@ -0,0 +1,141 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass, field + +import torch +import torch.nn.functional as F + +from fairseq import metrics +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class SentencePredictionConfig(FairseqDataclass): + classification_head_name: str = field( + default="sentence_classification_head", + metadata={"help": "name of the classification head to use"}, + ) + regression_target: bool = field( + default=False, + ) + + +@register_criterion("sentence_prediction", dataclass=SentencePredictionConfig) +class SentencePredictionCriterion(FairseqCriterion): + def __init__(self, cfg: SentencePredictionConfig, task): + super().__init__(task) + self.classification_head_name = cfg.classification_head_name + self.regression_target = cfg.regression_target + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + assert ( + hasattr(model, "classification_heads") + and self.classification_head_name in model.classification_heads + ), "model must provide sentence classification head for --criterion=sentence_prediction" + + logits, _ = model( + **sample["net_input"], + features_only=True, + classification_head_name=self.classification_head_name, + ) + targets = model.get_targets(sample, [logits]).view(-1) + sample_size = targets.numel() + + if not self.regression_target: + lprobs = F.log_softmax(logits, dim=-1, dtype=torch.float32) + task_loss = F.nll_loss(lprobs, targets, reduction="sum") + else: + logits = logits.view(-1).float() + targets = targets.float() + task_loss = F.mse_loss(logits, targets, reduction="sum") + + logging_output = {} + loss = task_loss + # mha & ffn regularization update + if ( + hasattr(model.args, "mha_reg_scale_factor") + and model.args.mha_reg_scale_factor != 0.0 + ): + mha_reg_loss = model._get_adaptive_head_loss() + loss += mha_reg_loss + logging_output.update({"mha_reg_loss": mha_reg_loss}) + if ( + hasattr(model.args, "ffn_reg_scale_factor") + and model.args.ffn_reg_scale_factor != 0.0 + ): + ffn_reg_loss = model._get_adaptive_ffn_loss() + loss += ffn_reg_loss + logging_output.update({"ffn_reg_loss": ffn_reg_loss}) + + logging_output.update( + { + "loss": loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample_size, + "sample_size": sample_size, + } + ) + if not self.regression_target: + preds = logits.argmax(dim=1) + logging_output["ncorrect"] = (preds == targets).sum() + + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = sum(log.get("loss", 0) for log in logging_outputs) + ntokens = sum(log.get("ntokens", 0) for log in logging_outputs) + nsentences = sum(log.get("nsentences", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + mha_reg_loss_sum = sum(log.get("mha_reg_loss", 0) for log in logging_outputs) + ffn_reg_loss_sum = sum(log.get("ffn_reg_loss", 0) for log in logging_outputs) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + if mha_reg_loss_sum: + metrics.log_scalar( + "mha_reg_loss", + mha_reg_loss_sum / sample_size / math.log(2), + sample_size, + round=3, + ) + if ffn_reg_loss_sum: + metrics.log_scalar( + "ffn_reg_loss", + ffn_reg_loss_sum / sample_size / math.log(2), + sample_size, + round=3, + ) + if sample_size != ntokens: + metrics.log_scalar( + "nll_loss", loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + + if len(logging_outputs) > 0 and "ncorrect" in logging_outputs[0]: + ncorrect = sum(log.get("ncorrect", 0) for log in logging_outputs) + metrics.log_scalar( + "accuracy", 100.0 * ncorrect / nsentences, nsentences, round=1 + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_prediction_adapters.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_prediction_adapters.py new file mode 100644 index 00000000..8a873a45 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_prediction_adapters.py @@ -0,0 +1,63 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn.functional as F +from fairseq.criterions import register_criterion +from fairseq.criterions.sentence_prediction import ( + SentencePredictionCriterion, + SentencePredictionConfig, +) + + +@register_criterion("sentence_prediction_adapters", dataclass=SentencePredictionConfig) +class SentencePredictionCriterionAdapters(SentencePredictionCriterion): + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + assert ( + hasattr(model, "classification_heads") + and self.classification_head_name in model.classification_heads + ), "model must provide sentence classification head for --criterion=sentence_prediction" + + if not hasattr(sample, "lang_id"): + # If no language ID is given, we fall back to English + lang_id = ["en_XX"] * sample["nsentences"] + else: + lang_id = sample["lang_id"] + + logits, _ = model( + **sample["net_input"], + features_only=True, + classification_head_name=self.classification_head_name, + lang_id=lang_id, + ) + targets = model.get_targets(sample, [logits]).view(-1) + sample_size = targets.numel() + + if not self.regression_target: + lprobs = F.log_softmax(logits, dim=-1, dtype=torch.float32) + loss = F.nll_loss(lprobs, targets, reduction="sum") + else: + logits = logits.view(-1).float() + targets = targets.float() + loss = F.mse_loss(logits, targets, reduction="sum") + + logging_output = { + "loss": loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample_size, + "sample_size": sample_size, + } + if not self.regression_target: + preds = logits.argmax(dim=1) + logging_output["ncorrect"] = (preds == targets).sum() + + return loss, sample_size, logging_output diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_ranking.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_ranking.py new file mode 100644 index 00000000..d4c76341 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/sentence_ranking.py @@ -0,0 +1,120 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch +import torch.nn.functional as F +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion + + +@register_criterion("sentence_ranking") +class SentenceRankingCriterion(FairseqCriterion): + def __init__(self, task, ranking_head_name, save_predictions, num_classes): + super().__init__(task) + self.ranking_head_name = ranking_head_name + if save_predictions is not None: + self.prediction_h = open(save_predictions, "w") + else: + self.prediction_h = None + self.num_classes = num_classes + + def __del__(self): + if self.prediction_h is not None: + self.prediction_h.close() + + @staticmethod + def add_args(parser): + # fmt: off + parser.add_argument('--save-predictions', metavar='FILE', + help='file to save predictions to') + parser.add_argument('--ranking-head-name', + default='sentence_classification_head', + help='name of the ranking head to use') + # fmt: on + + def forward(self, model, sample, reduce=True): + """Compute ranking loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + assert ( + hasattr(model, "classification_heads") + and self.ranking_head_name in model.classification_heads + ), "model must provide sentence ranking head for --criterion=sentence_ranking" + + scores = [] + for idx in range(self.num_classes): + score, _ = model( + **sample["net_input{idx}".format(idx=idx + 1)], + classification_head_name=self.ranking_head_name, + ) + scores.append(score) + + logits = torch.cat(scores, dim=1) + sample_size = logits.size(0) + + if "target" in sample: + targets = model.get_targets(sample, [logits]).view(-1) + lprobs = F.log_softmax(logits, dim=-1, dtype=torch.float32) + loss = F.nll_loss(lprobs, targets, reduction="sum") + else: + targets = None + loss = torch.tensor(0.0, requires_grad=True) + + if self.prediction_h is not None: + preds = logits.argmax(dim=1) + for i, (id, pred) in enumerate(zip(sample["id"].tolist(), preds.tolist())): + if targets is not None: + label = targets[i].item() + print("{}\t{}\t{}".format(id, pred, label), file=self.prediction_h) + else: + print("{}\t{}".format(id, pred), file=self.prediction_h) + + logging_output = { + "loss": loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample_size, + "sample_size": sample_size, + } + if targets is not None: + logging_output["ncorrect"] = (logits.argmax(dim=1) == targets).sum() + + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = sum(log.get("loss", 0) for log in logging_outputs) + ntokens = sum(log.get("ntokens", 0) for log in logging_outputs) + nsentences = sum(log.get("nsentences", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + if sample_size != ntokens: + metrics.log_scalar( + "nll_loss", loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + + if len(logging_outputs) > 0 and "ncorrect" in logging_outputs[0]: + ncorrect = sum(log.get("ncorrect", 0) for log in logging_outputs) + metrics.log_scalar( + "accuracy", 100.0 * ncorrect / nsentences, nsentences, round=1 + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/speech_to_speech_criterion.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/speech_to_speech_criterion.py new file mode 100644 index 00000000..7fba673d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/speech_to_speech_criterion.py @@ -0,0 +1,310 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +import torch + +from fairseq import metrics, utils +from fairseq.criterions import register_criterion +from fairseq.criterions.ctc import CtcCriterion +from fairseq.criterions.label_smoothed_cross_entropy import ( + LabelSmoothedCrossEntropyCriterion, + LabelSmoothedCrossEntropyCriterionConfig, +) +from fairseq.criterions.tacotron2_loss import ( + Tacotron2Criterion, + Tacotron2CriterionConfig, +) + + +class MultitaskCriterion: + def __init__(self, multitask_tasks): + self.multitask_criterion = {} + self.multitask_loss_weight = {} + for task_name, task_obj in multitask_tasks.items(): + if task_obj.args.decoder_type == "ctc": + self.multitask_criterion[task_name] = CtcCriterion( + task_obj.args.criterion_cfg, task_obj + ) + else: + self.multitask_criterion[ + task_name + ] = LabelSmoothedCrossEntropyCriterion( + task_obj, + task_obj.args.criterion_cfg.sentence_avg, + label_smoothing=task_obj.args.criterion_cfg.label_smoothing, + ) + + def set_multitask_loss_weight(self, task_name, weight=0.0): + self.multitask_loss_weight[task_name] = weight + + def get_multitask_loss(self, model, sample, model_out): + logging_output = {} + loss = 0.0 + for task_name, task_criterion in self.multitask_criterion.items(): + layer_id = task_criterion.task.args.input_layer + if isinstance(task_criterion, CtcCriterion): + if task_criterion.task.args.input_from == "encoder": + non_padding_mask = ~model_out["encoder_padding_mask"][0] + input_lengths = non_padding_mask.long().sum(-1) + task_sample = { + "net_input": { + "src_tokens": model_out["encoder_states"][ + layer_id + ], # check batch idx + "src_lengths": input_lengths, + }, + "id": sample["id"], + } + else: + task_sample = { + "net_input": { + "src_tokens": model_out["inner_states"][layer_id], + "src_lengths": sample["target_lengths"], + }, + "id": sample["id"], + } + else: + task_sample = { + "net_input": { + "src_tokens": sample["multitask"][task_name]["net_input"][ + "prev_output_tokens" + ], + "encoder_out": { + "encoder_out": [model_out["encoder_states"][layer_id]], + "encoder_padding_mask": model_out["encoder_padding_mask"], + }, + } + } + + for key in ["target", "target_lengths", "ntokens"]: + task_sample[key] = sample["multitask"][task_name][key] + + task_loss, task_sample_size, task_logging_output = task_criterion( + model.multitask_decoders[task_name], task_sample + ) + + loss = loss + self.multitask_loss_weight[task_name] * task_loss + task_logging_output["loss_weight"] = self.multitask_loss_weight[task_name] + logging_output[task_name] = task_logging_output + return loss, logging_output + + @classmethod + def reduce_metrics(cls, logging_outputs) -> None: + for task_name in logging_outputs[0]["multitask"].keys(): + # different criterion may return different logging + # currently only reduce on loss, the most common one + # ideally the way that losses are reduced should also depend on the task type + loss_sum = sum( + log["multitask"][task_name].get("loss", 0) for log in logging_outputs + ) + sample_size = sum( + log["multitask"][task_name].get("sample_size", 0) + for log in logging_outputs + ) + + metrics.log_scalar( + f"multitask_{task_name}_loss", + loss_sum / sample_size / math.log(2), + sample_size, + round=3, + ) + + loss_weight = logging_outputs[0]["multitask"][task_name].get( + "loss_weight", 0 + ) + metrics.log_scalar( + f"multitask_{task_name}_loss_weight", + loss_weight, + weight=0, + priority=250, + ) + + +@register_criterion( + "speech_to_unit", dataclass=LabelSmoothedCrossEntropyCriterionConfig +) +class SpeechToUnitMultitaskTaskCriterion( + LabelSmoothedCrossEntropyCriterion, MultitaskCriterion +): + def __init__( + self, + task, + sentence_avg, + label_smoothing, + ignore_prefix_size=0, + report_accuracy=False, + ): + super().__init__( + task, sentence_avg, label_smoothing, ignore_prefix_size, report_accuracy + ) + MultitaskCriterion.__init__(self, task.multitask_tasks) + + def forward(self, model, sample, reduce=True): + net_output, extra = model( + src_tokens=sample["net_input"]["src_tokens"], + src_lengths=sample["net_input"]["src_lengths"], + prev_output_tokens=sample["net_input"]["prev_output_tokens"], + tgt_speaker=sample["net_input"]["tgt_speaker"], + return_all_hiddens=True, + ) + + loss, nll_loss = self.compute_loss(model, [net_output], sample, reduce=reduce) + sample_size = ( + sample["target"].size(0) if self.sentence_avg else sample["ntokens"] + ) + logging_output = { + "loss": loss.data, + "nll_loss": nll_loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample["target"].size(0), + "sample_size": sample_size, + } + if self.report_accuracy: + n_correct, total = self.compute_accuracy(model, [net_output], sample) + logging_output["n_correct"] = utils.item(n_correct.data) + logging_output["total"] = utils.item(total.data) + + if len(self.multitask_criterion) == 0: + return loss, sample_size, logging_output + + # multitask + multitask_loss, multitask_log = self.get_multitask_loss(model, sample, extra) + loss += multitask_loss + logging_output["multitask"] = multitask_log + + return loss, sample_size, logging_output + + @classmethod + def reduce_metrics(cls, logging_outputs) -> None: + super().reduce_metrics(logging_outputs) + + # inference metrics + if "targ_frames" in logging_outputs[0]: + n = sum(log.get("norm_frames", 0) for log in logging_outputs) + for key, new_key in [ + ("mcd_loss", "mcd_loss"), + ("pred_frames", "pred_ratio"), + ("nins", "ins_rate"), + ("ndel", "del_rate"), + ]: + val = sum(log.get(key, 0) for log in logging_outputs) + metrics.log_scalar(new_key, val / n, n, round=3) + + if "multitask" not in logging_outputs[0]: + return + + MultitaskCriterion.reduce_metrics(logging_outputs) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return False + + +@register_criterion("speech_to_spectrogram", dataclass=Tacotron2CriterionConfig) +class SpeechToSpectrogramMultitaskTaskCriterion(Tacotron2Criterion, MultitaskCriterion): + def __init__( + self, + task, + sentence_avg, + use_guided_attention_loss, + guided_attention_loss_sigma, + bce_pos_weight, + ctc_weight, + ): + super().__init__( + task, + sentence_avg, + use_guided_attention_loss, + guided_attention_loss_sigma, + bce_pos_weight, + ctc_weight, + ) + MultitaskCriterion.__init__(self, task.multitask_tasks) + + def forward(self, model, sample, reduction="mean"): + bsz, max_len, _ = sample["target"].size() + feat_tgt = sample["target"] + feat_len = sample["target_lengths"].view(bsz, 1).expand(-1, max_len) + eos_tgt = torch.arange(max_len).to(sample["target"].device) + eos_tgt = eos_tgt.view(1, max_len).expand(bsz, -1) + eos_tgt = (eos_tgt == (feat_len - 1)).float() + + feat_out, eos_out, extra = model( + src_tokens=sample["net_input"]["src_tokens"], + src_lengths=sample["net_input"]["src_lengths"], + prev_output_tokens=sample["net_input"]["prev_output_tokens"], + tgt_speaker=sample["net_input"]["tgt_speaker"], + target_lengths=sample["target_lengths"], + return_all_hiddens=True, + ) + + l1_loss, mse_loss, eos_loss = self.compute_loss( + extra["feature_out"], + feat_out, + eos_out, + feat_tgt, + eos_tgt, + sample["target_lengths"], + reduction, + ) + attn_loss = torch.tensor(0.0).type_as(l1_loss) + if self.guided_attn is not None: + attn_loss = self.guided_attn( + extra["attn"], + sample["net_input"]["src_lengths"], + sample["target_lengths"], + reduction, + ) + loss = ( + l1_loss + mse_loss + eos_loss + attn_loss + ) # do not include ctc loss as there's no text target + + sample_size = sample["nsentences"] if self.sentence_avg else sample["ntokens"] + logging_output = { + "loss": utils.item(loss.data), + "ntokens": sample["ntokens"], + "nsentences": sample["nsentences"], + "sample_size": sample_size, + "l1_loss": utils.item(l1_loss.data), + "mse_loss": utils.item(mse_loss.data), + "eos_loss": utils.item(eos_loss.data), + "attn_loss": utils.item(attn_loss.data), + } + + if len(self.multitask_criterion) == 0: + return loss, sample_size, logging_output + + # multitask + multitask_loss, multitask_log = self.get_multitask_loss(model, sample, extra) + loss += multitask_loss + logging_output["multitask"] = multitask_log + return loss, sample_size, logging_output + + @classmethod + def reduce_metrics(cls, logging_outputs) -> None: + super().reduce_metrics(logging_outputs) + + # inference metrics + if "targ_frames" in logging_outputs[0]: + n = sum(log.get("norm_frames", 0) for log in logging_outputs) + for key, new_key in [ + ("mcd_loss", "mcd_loss"), + ("pred_frames", "pred_ratio"), + ("nins", "ins_rate"), + ("ndel", "del_rate"), + ]: + val = sum(log.get(key, 0) for log in logging_outputs) + metrics.log_scalar(new_key, val / n, n, round=3) + + if "multitask" not in logging_outputs[0]: + return + + MultitaskCriterion.reduce_metrics(logging_outputs) diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/speech_ulm_criterion.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/speech_ulm_criterion.py new file mode 100644 index 00000000..eae6b62f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/speech_ulm_criterion.py @@ -0,0 +1,126 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from dataclasses import dataclass, field + +import torch.nn.functional as F +from fairseq import metrics +from fairseq.tasks import FairseqTask +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass +from omegaconf import II + + +@dataclass +class SpeechUnitLmCriterionConfig(FairseqDataclass): + sentence_avg: bool = II("optimization.sentence_avg") + loss_weights: str = field( + default="1.;0.0;0.0", + metadata={ + "help": "Weights of the losses that correspond to token, duration, and F0 streams" + }, + ) + discrete_duration: bool = II("task.discrete_duration") + discrete_f0: bool = II("task.discrete_f0") + + +def mae_loss(pred, targ, mask, reduce=True): + if pred.ndim == 3: + pred = pred.squeeze(2) + else: + assert pred.ndim == 2 + loss = (pred.float() - targ.float()).abs() * (~mask).float() + loss = loss.sum() if reduce else loss.view(-1) + return loss + + +def nll_loss(pred, targ, mask, reduce=True): + lprob = F.log_softmax(pred, dim=-1) + loss = F.nll_loss(lprob.view(-1, lprob.size(-1)), targ.view(-1), reduction="none") + loss = loss * (~mask).float().view(-1) + loss = loss.sum() if reduce else loss.view(-1) + return loss + + +@register_criterion("speech_unit_lm_criterion", dataclass=SpeechUnitLmCriterionConfig) +class SpeechUnitLmCriterion(FairseqCriterion): + def __init__(self, cfg: SpeechUnitLmCriterionConfig, task: FairseqTask): + super().__init__(task) + self.sentence_avg = cfg.sentence_avg + self.weights = torch.tensor([float(w) for w in cfg.loss_weights.split(";")]) + assert self.weights.size(0) == 3 + assert (self.weights >= 0.0).all() + + self.dur_loss_fn = nll_loss if cfg.discrete_duration else mae_loss + self.f0_loss_fn = nll_loss if cfg.discrete_f0 else mae_loss + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + net_output = model(**sample["net_input"]) + + token_loss = nll_loss( + net_output["token"], sample["target"], sample["mask"], reduce + ) + dur_loss = self.dur_loss_fn( + net_output["duration"], + sample["dur_target"], + sample["dur_mask"], + reduce, + ) + f0_loss = self.f0_loss_fn( + net_output["f0"], + sample["f0_target"], + sample["f0_mask"], + reduce, + ) + loss = self.weights.to(token_loss.device) * torch.stack( + [token_loss, dur_loss, f0_loss], dim=-1 + ) + loss = loss.sum() if reduce else loss.sum(-1) + + sample_size = ( + sample["target"].size(0) if self.sentence_avg else sample["ntokens"] + ) + logging_output = { + "loss": loss.detach().sum().item(), + "token_loss": token_loss.detach().sum().item(), + "dur_loss": dur_loss.detach().sum().item(), + "f0_loss": f0_loss.detach().sum().item(), + "ntokens": sample["ntokens"], + "nsentences": sample["target"].size(0), + "sample_size": sample_size, + } + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = sum(log.get("loss", 0) for log in logging_outputs) + token_loss_sum = sum(log.get("token_loss", 0) for log in logging_outputs) + dur_loss_sum = sum(log.get("dur_loss", 0) for log in logging_outputs) + f0_loss_sum = sum(log.get("f0_loss", 0) for log in logging_outputs) + + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + + metrics.log_scalar("loss", loss_sum / sample_size, sample_size, round=3) + + metrics.log_scalar( + "token_loss", token_loss_sum / sample_size, sample_size, round=3 + ) + + metrics.log_scalar("dur_loss", dur_loss_sum / sample_size, sample_size, round=3) + + metrics.log_scalar("f0_loss", f0_loss_sum / sample_size, sample_size, round=3) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/tacotron2_loss.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/tacotron2_loss.py new file mode 100644 index 00000000..d3af9762 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/tacotron2_loss.py @@ -0,0 +1,226 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + +import logging +from dataclasses import dataclass, field +from functools import lru_cache +from typing import Any, Dict, List + +import torch +import torch.nn.functional as F +from omegaconf import II + +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.data.data_utils import lengths_to_mask +from fairseq.dataclass import FairseqDataclass + +logger = logging.getLogger(__name__) + + +@dataclass +class Tacotron2CriterionConfig(FairseqDataclass): + bce_pos_weight: float = field( + default=1.0, + metadata={"help": "weight of positive examples for BCE loss"}, + ) + use_guided_attention_loss: bool = field( + default=False, + metadata={"help": "use guided attention loss"}, + ) + guided_attention_loss_sigma: float = field( + default=0.4, + metadata={"help": "weight of positive examples for BCE loss"}, + ) + ctc_weight: float = field(default=0.0, metadata={"help": "weight for CTC loss"}) + sentence_avg: bool = II("optimization.sentence_avg") + + +class GuidedAttentionLoss(torch.nn.Module): + """ + Efficiently Trainable Text-to-Speech System Based on Deep Convolutional + Networks with Guided Attention (https://arxiv.org/abs/1710.08969) + """ + + def __init__(self, sigma): + super().__init__() + self.sigma = sigma + + @staticmethod + @lru_cache(maxsize=8) + def _get_weight(s_len, t_len, sigma): + grid_x, grid_y = torch.meshgrid(torch.arange(t_len), torch.arange(s_len)) + grid_x = grid_x.to(s_len.device) + grid_y = grid_y.to(s_len.device) + w = (grid_y.float() / s_len - grid_x.float() / t_len) ** 2 + return 1.0 - torch.exp(-w / (2 * (sigma**2))) + + def _get_weights(self, src_lens, tgt_lens): + bsz, max_s_len, max_t_len = len(src_lens), max(src_lens), max(tgt_lens) + weights = torch.zeros((bsz, max_t_len, max_s_len)) + for i, (s_len, t_len) in enumerate(zip(src_lens, tgt_lens)): + weights[i, :t_len, :s_len] = self._get_weight(s_len, t_len, self.sigma) + return weights + + @staticmethod + def _get_masks(src_lens, tgt_lens): + in_masks = lengths_to_mask(src_lens) + out_masks = lengths_to_mask(tgt_lens) + return out_masks.unsqueeze(2) & in_masks.unsqueeze(1) + + def forward(self, attn, src_lens, tgt_lens, reduction="mean"): + weights = self._get_weights(src_lens, tgt_lens).to(attn.device) + masks = self._get_masks(src_lens, tgt_lens).to(attn.device) + loss = (weights * attn.transpose(1, 2)).masked_select(masks) + loss = torch.sum(loss) if reduction == "sum" else torch.mean(loss) + return loss + + +@register_criterion("tacotron2", dataclass=Tacotron2CriterionConfig) +class Tacotron2Criterion(FairseqCriterion): + def __init__( + self, + task, + sentence_avg, + use_guided_attention_loss, + guided_attention_loss_sigma, + bce_pos_weight, + ctc_weight, + ): + super().__init__(task) + self.sentence_avg = sentence_avg + self.bce_pos_weight = bce_pos_weight + + self.guided_attn = None + if use_guided_attention_loss: + self.guided_attn = GuidedAttentionLoss(guided_attention_loss_sigma) + self.ctc_weight = ctc_weight + + def forward(self, model, sample, reduction="mean"): + bsz, max_len, _ = sample["target"].size() + feat_tgt = sample["target"] + feat_len = sample["target_lengths"].view(bsz, 1).expand(-1, max_len) + eos_tgt = torch.arange(max_len).to(sample["target"].device) + eos_tgt = eos_tgt.view(1, max_len).expand(bsz, -1) + eos_tgt = (eos_tgt == (feat_len - 1)).float() + src_tokens = sample["net_input"]["src_tokens"] + src_lens = sample["net_input"]["src_lengths"] + tgt_lens = sample["target_lengths"] + + feat_out, eos_out, extra = model( + src_tokens=src_tokens, + src_lengths=src_lens, + prev_output_tokens=sample["net_input"]["prev_output_tokens"], + incremental_state=None, + target_lengths=tgt_lens, + speaker=sample["speaker"], + ) + + l1_loss, mse_loss, eos_loss = self.compute_loss( + extra["feature_out"], + feat_out, + eos_out, + feat_tgt, + eos_tgt, + tgt_lens, + reduction, + ) + attn_loss = torch.tensor(0.0).type_as(l1_loss) + if self.guided_attn is not None: + attn_loss = self.guided_attn(extra["attn"], src_lens, tgt_lens, reduction) + ctc_loss = torch.tensor(0.0).type_as(l1_loss) + if self.ctc_weight > 0.0: + net_output = (feat_out, eos_out, extra) + lprobs = model.get_normalized_probs(net_output, log_probs=True) + lprobs = lprobs.transpose(0, 1) # T x B x C + src_mask = lengths_to_mask(src_lens) + src_tokens_flat = src_tokens.masked_select(src_mask) + ctc_loss = ( + F.ctc_loss( + lprobs, + src_tokens_flat, + tgt_lens, + src_lens, + reduction=reduction, + zero_infinity=True, + ) + * self.ctc_weight + ) + loss = l1_loss + mse_loss + eos_loss + attn_loss + ctc_loss + + sample_size = sample["nsentences"] if self.sentence_avg else sample["ntokens"] + logging_output = { + "loss": utils.item(loss.data), + "ntokens": sample["ntokens"], + "nsentences": sample["nsentences"], + "sample_size": sample_size, + "l1_loss": utils.item(l1_loss.data), + "mse_loss": utils.item(mse_loss.data), + "eos_loss": utils.item(eos_loss.data), + "attn_loss": utils.item(attn_loss.data), + "ctc_loss": utils.item(ctc_loss.data), + } + return loss, sample_size, logging_output + + def compute_loss( + self, + feat_out, + feat_out_post, + eos_out, + feat_tgt, + eos_tgt, + tgt_lens, + reduction="mean", + ): + mask = lengths_to_mask(tgt_lens) + _eos_out = eos_out[mask].squeeze() + _eos_tgt = eos_tgt[mask] + _feat_tgt = feat_tgt[mask] + _feat_out = feat_out[mask] + _feat_out_post = feat_out_post[mask] + + l1_loss = F.l1_loss(_feat_out, _feat_tgt, reduction=reduction) + F.l1_loss( + _feat_out_post, _feat_tgt, reduction=reduction + ) + mse_loss = F.mse_loss(_feat_out, _feat_tgt, reduction=reduction) + F.mse_loss( + _feat_out_post, _feat_tgt, reduction=reduction + ) + eos_loss = F.binary_cross_entropy_with_logits( + _eos_out, + _eos_tgt, + pos_weight=torch.tensor(self.bce_pos_weight), + reduction=reduction, + ) + return l1_loss, mse_loss, eos_loss + + @classmethod + def reduce_metrics(cls, logging_outputs: List[Dict[str, Any]]) -> None: + ns = [log.get("sample_size", 0) for log in logging_outputs] + ntot = sum(ns) + ws = [n / (ntot + 1e-8) for n in ns] + for key in ["loss", "l1_loss", "mse_loss", "eos_loss", "attn_loss", "ctc_loss"]: + vals = [log.get(key, 0) for log in logging_outputs] + val = sum(val * w for val, w in zip(vals, ws)) + metrics.log_scalar(key, val, ntot, round=3) + metrics.log_scalar("sample_size", ntot, len(logging_outputs)) + + # inference metrics + if "targ_frames" not in logging_outputs[0]: + return + n = sum(log.get("targ_frames", 0) for log in logging_outputs) + for key, new_key in [ + ("mcd_loss", "mcd_loss"), + ("pred_frames", "pred_ratio"), + ("nins", "ins_rate"), + ("ndel", "del_rate"), + ]: + val = sum(log.get(key, 0) for log in logging_outputs) + metrics.log_scalar(new_key, val / n, n, round=3) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + return False diff --git a/PyTorch/NLP/new-Transformer/fairseq/criterions/wav2vec_criterion.py b/PyTorch/NLP/new-Transformer/fairseq/criterions/wav2vec_criterion.py new file mode 100644 index 00000000..e37274d5 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/criterions/wav2vec_criterion.py @@ -0,0 +1,230 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass, field +from typing import List, Optional + +import torch +import torch.nn.functional as F +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion +from fairseq.dataclass import FairseqDataclass +from fairseq.logging.meters import safe_round +from fairseq.utils import is_xla_tensor + + +@dataclass +class Wav2VecCriterionConfig(FairseqDataclass): + infonce: bool = field( + default=False, + metadata={ + "help": "if set, uses cross entropy instead of binary cross entropy (i.e. InfoNCE loss)" + }, + ) + loss_weights: Optional[List[float]] = field( + default=None, + metadata={"help": "weights for additional loss terms (not first one)"}, + ) + log_keys: List[str] = field( + default_factory=lambda: [], + metadata={"help": "output keys to log"}, + ) + + +@register_criterion("wav2vec", dataclass=Wav2VecCriterionConfig) +class Wav2vecCriterion(FairseqCriterion): + def __init__(self, task, infonce=False, loss_weights=None, log_keys=None): + super().__init__(task) + self.infonce = infonce + self.loss_weights = loss_weights + self.log_keys = [] if log_keys is None else log_keys + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + net_output = model(**sample["net_input"]) + logits = model.get_logits(net_output).float() + target = model.get_targets(sample, net_output) + self.xla = is_xla_tensor(logits) + + # XXX: handle weights on xla. + weights = None + if hasattr(model, "get_target_weights") and not self.infonce: + weights = model.get_target_weights(target, net_output) + if torch.is_tensor(weights): + weights = weights.float() + + losses = [] + + reduction = "none" if ((not reduce) or self.xla) else "sum" + if self.infonce: + loss = F.cross_entropy(logits, target, reduction=reduction) + else: + loss = F.binary_cross_entropy_with_logits( + logits, target.float(), weights, reduction=reduction + ) + + if self.xla: + # tpu-comment: since dynamic shapes lead to recompilations on xla, + # we don't shrink tensors using mask_indices. + # Instead, we use mask indices to adjust loss. + mi = ( + sample["net_input"]["mask_indices"] + .transpose(0, 1) # logits are transposed in `model.get_logits` + .reshape(logits.size(0)) + ) + loss = (loss * mi).sum() if reduce else (loss * mi) + + if "sample_size" in sample: + sample_size = sample["sample_size"] + elif "mask_indices" in sample["net_input"]: + sample_size = sample["net_input"]["mask_indices"].sum() + else: + sample_size = target.numel() if self.infonce else target.long().sum().item() + losses.append(loss.detach().clone()) + + if self.loss_weights is not None: + assert hasattr(model, "get_extra_losses") + extra_losses = model.get_extra_losses(net_output) + if torch.is_tensor(extra_losses): + extra_losses = [extra_losses] + if len(self.loss_weights) == 1 and len(extra_losses) != 1: + self.loss_weights = [self.loss_weights[0]] * len(extra_losses) + assert len(extra_losses) == len( + self.loss_weights + ), f"{len(extra_losses)}, {len(self.loss_weights)}" + for p, coef in zip(extra_losses, self.loss_weights): + if coef != 0 and p is not None: + p = coef * p.float() * sample_size + loss += p + losses.append(p) + + logging_output = { + "loss": loss.item() if (reduce and not self.xla) else loss.detach(), + "ntokens": sample_size, + "nsentences": sample["id"].numel(), + "sample_size": sample_size, + } + + for lk in self.log_keys: + # Only store "logits" and "target" for computing MAP and MAUC + # during validation + if lk == "logits": + if not self.training: + logging_output["logits"] = logits.cpu().numpy() + elif lk == "target": + if not self.training: + # If the targets have been mixed with the predictions of + # teacher models, find the original targets + if hasattr(model, "get_original_targets"): + original_target = model.get_original_targets(sample, net_output) + else: + original_target = target + logging_output["target"] = original_target.cpu().numpy() + elif lk in net_output: + value = net_output[lk] + if not is_xla_tensor(value): + value = float(value) + logging_output[lk] = value + + if len(losses) > 1: + for i, l in enumerate(losses): + logging_output[f"loss_{i}"] = l.item() if not self.xla else l.detach() + + if self.infonce: + with torch.no_grad(): + if logits.numel() == 0: + corr = 0 + count = 0 + else: + assert logits.dim() > 1, logits.shape + max = logits.argmax(-1) == 0 + min = logits.argmin(-1) == 0 + if is_xla_tensor(logits): + max, min = max * mi, min * mi + both = max & min + corr = max.long().sum() - both.long().sum() + count = mi.sum() + else: + both = max & min + corr = max.long().sum().item() - both.long().sum().item() + count = float(max.numel()) + + logging_output["correct"] = corr + logging_output["count"] = count + + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = utils.item(sum(log.get("loss", 0) for log in logging_outputs)) + ntokens = utils.item(sum(log.get("ntokens", 0) for log in logging_outputs)) + nsentences = utils.item( + sum(log.get("nsentences", 0) for log in logging_outputs) + ) + sample_size = utils.item( + sum(log.get("sample_size", 0) for log in logging_outputs) + ) + + metrics.log_scalar( + "loss", loss_sum / (sample_size or 1) / math.log(2), sample_size, round=3 + ) + metrics.log_scalar("ntokens", ntokens) + metrics.log_scalar("nsentences", nsentences) + + correct = sum(log.get("correct", 0) for log in logging_outputs) + metrics.log_scalar("_correct", correct) + + total = sum(log.get("count", 0) for log in logging_outputs) + metrics.log_scalar("_total", total) + + if total > 0: + metrics.log_derived( + "accuracy", + lambda meters: safe_round( + meters["_correct"].sum / meters["_total"].sum, 5 + ) + if meters["_total"].sum > 0 + else float("nan"), + ) + + builtin_keys = { + "loss", + "ntokens", + "nsentences", + "sample_size", + "correct", + "count", + } + + for k in logging_outputs[0]: + if k not in builtin_keys: + val = sum(log.get(k, 0) for log in logging_outputs) + if k.startswith("loss"): + metrics.log_scalar( + k, val / (sample_size or 1) / math.log(2), sample_size, round=3 + ) + else: + metrics.log_scalar(k, val / len(logging_outputs), round=3) + + # FIXME: revert when gather based xla reduction is implemented + # @staticmethod + # def logging_outputs_can_be_summed() -> bool: + def logging_outputs_can_be_summed(self) -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + # XXX: Gather based reduction not implemented for xla yet. + # So we fall to sum based reduction for xla. + return self.xla diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/data/__init__.py new file mode 100644 index 00000000..8acf2ca1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/__init__.py @@ -0,0 +1,130 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +from .dictionary import Dictionary, TruncatedDictionary + +from .fairseq_dataset import FairseqDataset, FairseqIterableDataset + +from .base_wrapper_dataset import BaseWrapperDataset + +from .add_target_dataset import AddTargetDataset +from .append_token_dataset import AppendTokenDataset +from .audio.raw_audio_dataset import BinarizedAudioDataset, FileAudioDataset +from .audio.hubert_dataset import HubertDataset +from .backtranslation_dataset import BacktranslationDataset +from .bucket_pad_length_dataset import BucketPadLengthDataset +from .colorize_dataset import ColorizeDataset +from .concat_dataset import ConcatDataset +from .concat_sentences_dataset import ConcatSentencesDataset +from .denoising_dataset import DenoisingDataset +from .id_dataset import IdDataset +from .indexed_dataset import ( + IndexedCachedDataset, + IndexedDataset, + IndexedRawTextDataset, + MMapIndexedDataset, +) +from .language_pair_dataset import LanguagePairDataset +from .list_dataset import ListDataset +from .lm_context_window_dataset import LMContextWindowDataset +from .lru_cache_dataset import LRUCacheDataset +from .mask_tokens_dataset import MaskTokensDataset +from .monolingual_dataset import MonolingualDataset +from .multi_corpus_sampled_dataset import MultiCorpusSampledDataset +from .nested_dictionary_dataset import NestedDictionaryDataset +from .noising import NoisingDataset +from .numel_dataset import NumelDataset +from .num_samples_dataset import NumSamplesDataset +from .offset_tokens_dataset import OffsetTokensDataset +from .pad_dataset import LeftPadDataset, PadDataset, RightPadDataset +from .prepend_dataset import PrependDataset +from .prepend_token_dataset import PrependTokenDataset +from .raw_label_dataset import RawLabelDataset +from .replace_dataset import ReplaceDataset +from .resampling_dataset import ResamplingDataset +from .roll_dataset import RollDataset +from .round_robin_zip_datasets import RoundRobinZipDatasets +from .sort_dataset import SortDataset +from .strip_token_dataset import StripTokenDataset +from .subsample_dataset import SubsampleDataset +from .token_block_dataset import TokenBlockDataset +from .transform_eos_dataset import TransformEosDataset +from .transform_eos_lang_pair_dataset import TransformEosLangPairDataset +from .shorten_dataset import TruncateDataset, RandomCropDataset +from .multilingual.sampled_multi_dataset import SampledMultiDataset +from .multilingual.sampled_multi_epoch_dataset import SampledMultiEpochDataset +from .fasta_dataset import FastaDataset, EncodedFastaDataset +from .transform_eos_concat_langpair_dataset import TransformEosConcatLangPairDataset + +from .iterators import ( + CountingIterator, + EpochBatchIterator, + GroupedIterator, + ShardedIterator, +) + +__all__ = [ + "AddTargetDataset", + "AppendTokenDataset", + "BacktranslationDataset", + "BaseWrapperDataset", + "BinarizedAudioDataset", + "BucketPadLengthDataset", + "ColorizeDataset", + "ConcatDataset", + "ConcatSentencesDataset", + "CountingIterator", + "DenoisingDataset", + "Dictionary", + "EncodedFastaDataset", + "EpochBatchIterator", + "FairseqDataset", + "FairseqIterableDataset", + "FastaDataset", + "FileAudioDataset", + "GroupedIterator", + "HubertDataset", + "IdDataset", + "IndexedCachedDataset", + "IndexedDataset", + "IndexedRawTextDataset", + "LanguagePairDataset", + "LeftPadDataset", + "ListDataset", + "LMContextWindowDataset", + "LRUCacheDataset", + "MaskTokensDataset", + "MMapIndexedDataset", + "MonolingualDataset", + "MultiCorpusSampledDataset", + "NestedDictionaryDataset", + "NoisingDataset", + "NumelDataset", + "NumSamplesDataset", + "OffsetTokensDataset", + "PadDataset", + "PrependDataset", + "PrependTokenDataset", + "RandomCropDataset", + "RawLabelDataset", + "ResamplingDataset", + "ReplaceDataset", + "RightPadDataset", + "RollDataset", + "RoundRobinZipDatasets", + "SampledMultiDataset", + "SampledMultiEpochDataset", + "ShardedIterator", + "SortDataset", + "StripTokenDataset", + "SubsampleDataset", + "TokenBlockDataset", + "TransformEosDataset", + "TransformEosLangPairDataset", + "TransformEosConcatLangPairDataset", + "TruncateDataset", + "TruncatedDictionary", +] diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/add_target_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/add_target_dataset.py new file mode 100644 index 00000000..978a5b19 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/add_target_dataset.py @@ -0,0 +1,83 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +from . import BaseWrapperDataset, data_utils +from fairseq.data.text_compressor import TextCompressor, TextCompressionLevel + + +class AddTargetDataset(BaseWrapperDataset): + def __init__( + self, + dataset, + labels, + pad, + eos, + batch_targets, + process_label=None, + label_len_fn=None, + add_to_input=False, + text_compression_level=TextCompressionLevel.none, + ): + super().__init__(dataset) + self.labels = labels + self.batch_targets = batch_targets + self.pad = pad + self.eos = eos + self.process_label = process_label + self.label_len_fn = label_len_fn + self.add_to_input = add_to_input + self.text_compressor = TextCompressor(level=text_compression_level) + + def get_label(self, index, process_fn=None): + lbl = self.labels[index] + lbl = self.text_compressor.decompress(lbl) + return lbl if process_fn is None else process_fn(lbl) + + def __getitem__(self, index): + item = self.dataset[index] + item["label"] = self.get_label(index, process_fn=self.process_label) + return item + + def size(self, index): + sz = self.dataset.size(index) + own_sz = self.label_len_fn(self.get_label(index)) + return sz, own_sz + + def collater(self, samples): + collated = self.dataset.collater(samples) + if len(collated) == 0: + return collated + indices = set(collated["id"].tolist()) + target = [s["label"] for s in samples if s["id"] in indices] + + if self.add_to_input: + eos = torch.LongTensor([self.eos]) + prev_output_tokens = [torch.cat([eos, t], axis=-1) for t in target] + target = [torch.cat([t, eos], axis=-1) for t in target] + collated["net_input"]["prev_output_tokens"] = prev_output_tokens + + if self.batch_targets: + collated["target_lengths"] = torch.LongTensor([len(t) for t in target]) + target = data_utils.collate_tokens(target, pad_idx=self.pad, left_pad=False) + collated["ntokens"] = collated["target_lengths"].sum().item() + if getattr(collated["net_input"], "prev_output_tokens", None): + collated["net_input"]["prev_output_tokens"] = data_utils.collate_tokens( + collated["net_input"]["prev_output_tokens"], + pad_idx=self.pad, + left_pad=False, + ) + else: + collated["ntokens"] = sum([len(t) for t in target]) + + collated["target"] = target + return collated + + def filter_indices_by_size(self, indices, max_sizes): + indices, ignored = data_utils._filter_by_size_dynamic( + indices, self.size, max_sizes + ) + return indices, ignored diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/append_token_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/append_token_dataset.py new file mode 100644 index 00000000..87695bd0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/append_token_dataset.py @@ -0,0 +1,41 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch + +from . import BaseWrapperDataset + + +class AppendTokenDataset(BaseWrapperDataset): + def __init__(self, dataset, token=None): + super().__init__(dataset) + self.token = token + if token is not None: + self._sizes = np.array(dataset.sizes) + 1 + else: + self._sizes = dataset.sizes + + def __getitem__(self, idx): + item = self.dataset[idx] + if self.token is not None: + item = torch.cat([item, item.new([self.token])]) + return item + + @property + def sizes(self): + return self._sizes + + def num_tokens(self, index): + n = self.dataset.num_tokens(index) + if self.token is not None: + n += 1 + return n + + def size(self, index): + n = self.dataset.size(index) + if self.token is not None: + n += 1 + return n diff --git a/PyTorch/NLP/Transformer/scripts/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/__init__.py similarity index 100% rename from PyTorch/NLP/Transformer/scripts/__init__.py rename to PyTorch/NLP/new-Transformer/fairseq/data/audio/__init__.py diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/audio_utils.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/audio_utils.py new file mode 100644 index 00000000..349b86c1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/audio_utils.py @@ -0,0 +1,293 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +import mmap +from pathlib import Path +from typing import BinaryIO, List, Optional, Tuple, Union + +import numpy as np +import torch +import torch.nn.functional as F + +SF_AUDIO_FILE_EXTENSIONS = {".wav", ".flac", ".ogg"} +FEATURE_OR_SF_AUDIO_FILE_EXTENSIONS = {".npy", ".wav", ".flac", ".ogg"} + + +def convert_waveform( + waveform: Union[np.ndarray, torch.Tensor], + sample_rate: int, + normalize_volume: bool = False, + to_mono: bool = False, + to_sample_rate: Optional[int] = None, +) -> Tuple[Union[np.ndarray, torch.Tensor], int]: + """convert a waveform: + - to a target sample rate + - from multi-channel to mono channel + - volume normalization + + Args: + waveform (numpy.ndarray or torch.Tensor): 2D original waveform + (channels x length) + sample_rate (int): original sample rate + normalize_volume (bool): perform volume normalization + to_mono (bool): convert to mono channel if having multiple channels + to_sample_rate (Optional[int]): target sample rate + Returns: + waveform (numpy.ndarray): converted 2D waveform (channels x length) + sample_rate (float): target sample rate + """ + try: + import torchaudio.sox_effects as ta_sox + except ImportError: + raise ImportError("Please install torchaudio: pip install torchaudio") + + effects = [] + if normalize_volume: + effects.append(["gain", "-n"]) + if to_sample_rate is not None and to_sample_rate != sample_rate: + effects.append(["rate", f"{to_sample_rate}"]) + if to_mono and waveform.shape[0] > 1: + effects.append(["channels", "1"]) + if len(effects) > 0: + is_np_input = isinstance(waveform, np.ndarray) + _waveform = torch.from_numpy(waveform) if is_np_input else waveform + converted, converted_sample_rate = ta_sox.apply_effects_tensor( + _waveform, sample_rate, effects + ) + if is_np_input: + converted = converted.numpy() + return converted, converted_sample_rate + return waveform, sample_rate + + +def get_waveform( + path_or_fp: Union[str, BinaryIO], + normalization: bool = True, + mono: bool = True, + frames: int = -1, + start: int = 0, + always_2d: bool = True, + output_sample_rate: Optional[int] = None, + normalize_volume: bool = False, +) -> Tuple[np.ndarray, int]: + """Get the waveform and sample rate of a 16-bit WAV/FLAC/OGG Vorbis audio. + + Args: + path_or_fp (str or BinaryIO): the path or file-like object + normalization (bool): normalize values to [-1, 1] (Default: True) + mono (bool): convert multi-channel audio to mono-channel one + frames (int): the number of frames to read. (-1 for reading all) + start (int): Where to start reading. A negative value counts from the end. + always_2d (bool): always return 2D array even for mono-channel audios + output_sample_rate (Optional[int]): output sample rate + normalize_volume (bool): normalize volume + Returns: + waveform (numpy.ndarray): 1D or 2D waveform (channels x length) + sample_rate (float): sample rate + """ + if isinstance(path_or_fp, str): + ext = Path(path_or_fp).suffix + if ext not in SF_AUDIO_FILE_EXTENSIONS: + raise ValueError(f"Unsupported audio format: {ext}") + + try: + import soundfile as sf + except ImportError: + raise ImportError("Please install soundfile: pip install soundfile") + + waveform, sample_rate = sf.read( + path_or_fp, dtype="float32", always_2d=True, frames=frames, start=start + ) + waveform = waveform.T # T x C -> C x T + waveform, sample_rate = convert_waveform( + waveform, + sample_rate, + normalize_volume=normalize_volume, + to_mono=mono, + to_sample_rate=output_sample_rate, + ) + + if not normalization: + waveform *= 2**15 # denormalized to 16-bit signed integers + if not always_2d: + waveform = waveform.squeeze(axis=0) + return waveform, sample_rate + + +def _get_kaldi_fbank( + waveform: np.ndarray, sample_rate: int, n_bins=80 +) -> Optional[np.ndarray]: + """Get mel-filter bank features via PyKaldi.""" + try: + from kaldi.feat.fbank import Fbank, FbankOptions + from kaldi.feat.mel import MelBanksOptions + from kaldi.feat.window import FrameExtractionOptions + from kaldi.matrix import Vector + + mel_opts = MelBanksOptions() + mel_opts.num_bins = n_bins + frame_opts = FrameExtractionOptions() + frame_opts.samp_freq = sample_rate + opts = FbankOptions() + opts.mel_opts = mel_opts + opts.frame_opts = frame_opts + fbank = Fbank(opts=opts) + features = fbank.compute(Vector(waveform.squeeze()), 1.0).numpy() + return features + except ImportError: + return None + + +def _get_torchaudio_fbank( + waveform: np.ndarray, sample_rate, n_bins=80 +) -> Optional[np.ndarray]: + """Get mel-filter bank features via TorchAudio.""" + try: + import torchaudio.compliance.kaldi as ta_kaldi + + waveform = torch.from_numpy(waveform) + features = ta_kaldi.fbank( + waveform, num_mel_bins=n_bins, sample_frequency=sample_rate + ) + return features.numpy() + except ImportError: + return None + + +def get_fbank(path_or_fp: Union[str, BinaryIO], n_bins=80) -> np.ndarray: + """Get mel-filter bank features via PyKaldi or TorchAudio. Prefer PyKaldi + (faster CPP implementation) to TorchAudio (Python implementation). Note that + Kaldi/TorchAudio requires 16-bit signed integers as inputs and hence the + waveform should not be normalized.""" + waveform, sample_rate = get_waveform(path_or_fp, normalization=False) + + features = _get_kaldi_fbank(waveform, sample_rate, n_bins) + if features is None: + features = _get_torchaudio_fbank(waveform, sample_rate, n_bins) + if features is None: + raise ImportError( + "Please install pyKaldi or torchaudio to enable " + "online filterbank feature extraction" + ) + + return features + + +def is_npy_data(data: bytes) -> bool: + return data[0] == 147 and data[1] == 78 + + +def is_sf_audio_data(data: bytes) -> bool: + is_wav = data[0] == 82 and data[1] == 73 and data[2] == 70 + is_flac = data[0] == 102 and data[1] == 76 and data[2] == 97 + is_ogg = data[0] == 79 and data[1] == 103 and data[2] == 103 + return is_wav or is_flac or is_ogg + + +def mmap_read(path: str, offset: int, length: int) -> bytes: + with open(path, "rb") as f: + with mmap.mmap(f.fileno(), length=0, access=mmap.ACCESS_READ) as mmap_o: + data = mmap_o[offset : offset + length] + return data + + +def read_from_stored_zip(zip_path: str, offset: int, length: int) -> bytes: + return mmap_read(zip_path, offset, length) + + +def parse_path(path: str) -> Tuple[str, List[int]]: + """Parse data path which is either a path to + 1. a .npy/.wav/.flac/.ogg file + 2. a stored ZIP file with slicing info: "[zip_path]:[offset]:[length]" + + Args: + path (str): the data path to parse + + Returns: + file_path (str): the file path + slice_ptr (list of int): empty in case 1; + byte offset and length for the slice in case 2 + """ + + if Path(path).suffix in FEATURE_OR_SF_AUDIO_FILE_EXTENSIONS: + _path, slice_ptr = path, [] + else: + _path, *slice_ptr = path.split(":") + if not Path(_path).is_file(): + raise FileNotFoundError(f"File not found: {_path}") + assert len(slice_ptr) in {0, 2}, f"Invalid path: {path}" + slice_ptr = [int(i) for i in slice_ptr] + return _path, slice_ptr + + +def get_window(window_fn: callable, n_fft: int, win_length: int) -> torch.Tensor: + padding = n_fft - win_length + assert padding >= 0 + return F.pad(window_fn(win_length), (padding // 2, padding - padding // 2)) + + +def get_fourier_basis(n_fft: int) -> torch.Tensor: + basis = np.fft.fft(np.eye(n_fft)) + basis = np.vstack( + [np.real(basis[: n_fft // 2 + 1, :]), np.imag(basis[: n_fft // 2 + 1, :])] + ) + return torch.from_numpy(basis).float() + + +def get_mel_filters( + sample_rate: int, n_fft: int, n_mels: int, f_min: float, f_max: float +) -> torch.Tensor: + try: + import librosa + except ImportError: + raise ImportError("Please install librosa: pip install librosa") + basis = librosa.filters.mel(sample_rate, n_fft, n_mels, f_min, f_max) + return torch.from_numpy(basis).float() + + +class TTSSpectrogram(torch.nn.Module): + def __init__( + self, + n_fft: int, + win_length: int, + hop_length: int, + window_fn: callable = torch.hann_window, + return_phase: bool = False, + ) -> None: + super(TTSSpectrogram, self).__init__() + self.n_fft = n_fft + self.hop_length = hop_length + self.return_phase = return_phase + + basis = get_fourier_basis(n_fft).unsqueeze(1) + basis *= get_window(window_fn, n_fft, win_length) + self.register_buffer("basis", basis) + + def forward( + self, waveform: torch.Tensor + ) -> Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]]: + padding = (self.n_fft // 2, self.n_fft // 2) + x = F.pad(waveform.unsqueeze(1), padding, mode="reflect") + x = F.conv1d(x, self.basis, stride=self.hop_length) + real_part = x[:, : self.n_fft // 2 + 1, :] + imag_part = x[:, self.n_fft // 2 + 1 :, :] + magnitude = torch.sqrt(real_part**2 + imag_part**2) + if self.return_phase: + phase = torch.atan2(imag_part, real_part) + return magnitude, phase + return magnitude + + +class TTSMelScale(torch.nn.Module): + def __init__( + self, n_mels: int, sample_rate: int, f_min: float, f_max: float, n_stft: int + ) -> None: + super(TTSMelScale, self).__init__() + basis = get_mel_filters(sample_rate, (n_stft - 1) * 2, n_mels, f_min, f_max) + self.register_buffer("basis", basis) + + def forward(self, specgram: torch.Tensor) -> torch.Tensor: + return torch.matmul(self.basis, specgram) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/data_cfg.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/data_cfg.py new file mode 100644 index 00000000..fba36dfc --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/data_cfg.py @@ -0,0 +1,299 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +from argparse import Namespace +from pathlib import Path +from typing import Dict, Optional + +from fairseq.data import Dictionary + + +def get_config_from_yaml(yaml_path: Path): + try: + import yaml + except ImportError: + print("Please install PyYAML: pip install PyYAML") + config = {} + if yaml_path.is_file(): + try: + with open(yaml_path) as f: + config = yaml.load(f, Loader=yaml.FullLoader) + except Exception as e: + raise Exception(f"Failed to load config from {yaml_path.as_posix()}: {e}") + else: + raise FileNotFoundError(f"{yaml_path.as_posix()} not found") + + return config + + +class S2TDataConfig(object): + """Wrapper class for data config YAML""" + + def __init__(self, yaml_path: Path): + self.config = get_config_from_yaml(yaml_path) + self.root = yaml_path.parent + + def _auto_convert_to_abs_path(self, x): + if isinstance(x, str): + if not Path(x).exists() and (self.root / x).exists(): + return (self.root / x).as_posix() + elif isinstance(x, dict): + return {k: self._auto_convert_to_abs_path(v) for k, v in x.items()} + return x + + @property + def vocab_filename(self): + """fairseq vocabulary file under data root""" + return self.config.get("vocab_filename", "dict.txt") + + @property + def speaker_set_filename(self): + """speaker set file under data root""" + return self.config.get("speaker_set_filename", None) + + @property + def shuffle(self) -> bool: + """Shuffle dataset samples before batching""" + return self.config.get("shuffle", False) + + @property + def pre_tokenizer(self) -> Dict: + """Pre-tokenizer to apply before subword tokenization. Returning + a dictionary with `tokenizer` providing the tokenizer name and + the other items providing the tokenizer-specific arguments. + Tokenizers are defined in `fairseq.data.encoders.*`""" + tokenizer = self.config.get("pre_tokenizer", {"tokenizer": None}) + return self._auto_convert_to_abs_path(tokenizer) + + @property + def bpe_tokenizer(self) -> Dict: + """Subword tokenizer to apply after pre-tokenization. Returning + a dictionary with `bpe` providing the tokenizer name and + the other items providing the tokenizer-specific arguments. + Tokenizers are defined in `fairseq.data.encoders.*`""" + tokenizer = self.config.get("bpe_tokenizer", {"bpe": None}) + return self._auto_convert_to_abs_path(tokenizer) + + @property + def prepend_tgt_lang_tag(self) -> bool: + """Prepend target lang ID token as the target BOS (e.g. for to-many + multilingual setting). During inference, this requires `--prefix-size 1` + to force BOS to be lang ID token.""" + return self.config.get("prepend_tgt_lang_tag", False) + + @property + def prepend_bos_and_append_tgt_lang_tag(self) -> bool: + """Prepend BOS and append target lang ID token to the target (e.g. mBART with language token pretraining).""" + return self.config.get("prepend_bos_and_append_tgt_lang_tag", False) + + @property + def input_feat_per_channel(self): + """The dimension of input features (per audio channel)""" + return self.config.get("input_feat_per_channel", 80) + + @property + def input_channels(self): + """The number of channels in the input audio""" + return self.config.get("input_channels", 1) + + @property + def sample_rate(self): + return self.config.get("sample_rate", 16_000) + + @property + def sampling_alpha(self): + """Hyper-parameter alpha = 1/T for temperature-based resampling. + (alpha = 1 for no resampling)""" + return self.config.get("sampling_alpha", 1.0) + + @property + def use_audio_input(self): + """Needed by the dataset loader to see if the model requires + raw audio as inputs.""" + return self.config.get("use_audio_input", False) + + def standardize_audio(self) -> bool: + return self.use_audio_input and self.config.get("standardize_audio", False) + + @property + def use_sample_rate(self): + """Needed by the dataset loader to see if the model requires + raw audio with specific sample rate as inputs.""" + return self.config.get("use_sample_rate", 16000) + + @property + def audio_root(self): + """Audio paths in the manifest TSV can be relative and this provides + the root path. Set this to empty string when using absolute paths.""" + return self.config.get("audio_root", "") + + def get_feature_transforms(self, split, is_train): + """Split-specific feature transforms. Allowing train set + wildcard `_train`, evaluation set wildcard `_eval` and general + wildcard `*` for matching.""" + from copy import deepcopy + + cfg = deepcopy(self.config) + _cur = cfg.get("transforms", {}) + cur = _cur.get(split) + cur = _cur.get("_train") if cur is None and is_train else cur + cur = _cur.get("_eval") if cur is None and not is_train else cur + cur = _cur.get("*") if cur is None else cur + cfg["transforms"] = cur + return cfg + + @property + def global_cmvn_stats_npz(self) -> Optional[str]: + path = self.config.get("global_cmvn", {}).get("stats_npz_path", None) + return self._auto_convert_to_abs_path(path) + + @property + def vocoder(self) -> Dict[str, str]: + vocoder = self.config.get("vocoder", {"type": "griffin_lim"}) + return self._auto_convert_to_abs_path(vocoder) + + @property + def hub(self) -> Dict[str, str]: + return self.config.get("hub", {}) + + +class S2SDataConfig(S2TDataConfig): + """Wrapper class for data config YAML""" + + @property + def vocab_filename(self): + """fairseq vocabulary file under data root""" + return self.config.get("vocab_filename", None) + + @property + def pre_tokenizer(self) -> Dict: + return None + + @property + def bpe_tokenizer(self) -> Dict: + return None + + @property + def input_transformed_channels(self): + """The number of channels in the audio after feature transforms""" + # TODO: move this into individual transforms + _cur = self.config.get("transforms", {}) + cur = _cur.get("_train", []) + + _channels = self.input_channels + if "delta_deltas" in cur: + _channels *= 3 + + return _channels + + @property + def output_sample_rate(self): + """The audio sample rate of output target speech""" + return self.config.get("output_sample_rate", 22050) + + @property + def target_speaker_embed(self): + """Target speaker embedding file (one line per target audio sample)""" + return self.config.get("target_speaker_embed", None) + + @property + def prepend_tgt_lang_tag_as_bos(self) -> bool: + """Prepend target lang ID token as the target BOS.""" + return self.config.get("prepend_tgt_lang_tag_as_bos", False) + + +class MultitaskConfig(object): + """Wrapper class for data config YAML""" + + def __init__(self, yaml_path: Path): + config = get_config_from_yaml(yaml_path) + self.config = {} + for k, v in config.items(): + self.config[k] = SingleTaskConfig(k, v) + + def get_all_tasks(self): + return self.config + + def get_single_task(self, name): + assert name in self.config, f"multitask '{name}' does not exist!" + return self.config[name] + + +class SingleTaskConfig(object): + def __init__(self, name, config): + self.task_name = name + self.config = config + dict_path = config.get("dict", "") + self.tgt_dict = Dictionary.load(dict_path) if Path(dict_path).exists() else None + + @property + def data(self): + return self.config.get("data", "") + + @property + def decoder_type(self): + return self.config.get("decoder_type", "transformer") + + @property + def decoder_args(self): + """Decoder arch related args""" + args = self.config.get("decoder_args", {}) + return Namespace(**args) + + @property + def criterion_cfg(self): + """cfg for the multitask criterion""" + if self.decoder_type == "ctc": + from fairseq.criterions.ctc import CtcCriterionConfig + + cfg = CtcCriterionConfig + cfg.zero_infinity = self.config.get("zero_infinity", True) + else: + from fairseq.criterions.label_smoothed_cross_entropy import ( + LabelSmoothedCrossEntropyCriterionConfig, + ) + + cfg = LabelSmoothedCrossEntropyCriterionConfig + cfg.label_smoothing = self.config.get("label_smoothing", 0.2) + return cfg + + @property + def input_from(self): + """Condition on encoder/decoder of the main model""" + return "decoder" if "decoder_layer" in self.config else "encoder" + + @property + def input_layer(self): + if self.input_from == "decoder": + return self.config["decoder_layer"] - 1 + else: + # default using the output from the last encoder layer (-1) + return self.config.get("encoder_layer", 0) - 1 + + @property + def loss_weight_schedule(self): + return ( + "decay" + if "loss_weight_max" in self.config + and "loss_weight_decay_steps" in self.config + else "fixed" + ) + + def get_loss_weight(self, num_updates): + if self.loss_weight_schedule == "fixed": + weight = self.config.get("loss_weight", 1.0) + else: # "decay" + assert ( + self.config.get("loss_weight_decay_steps", 0) > 0 + ), "loss_weight_decay_steps must be greater than 0 for a decay schedule" + loss_weight_min = self.config.get("loss_weight_min", 0.0001) + loss_weight_decay_stepsize = ( + self.config["loss_weight_max"] - loss_weight_min + ) / self.config["loss_weight_decay_steps"] + weight = max( + self.config["loss_weight_max"] + - loss_weight_decay_stepsize * num_updates, + loss_weight_min, + ) + return weight diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/__init__.py new file mode 100644 index 00000000..359fa069 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/__init__.py @@ -0,0 +1,82 @@ +import importlib +import os +from abc import ABC, abstractmethod +from typing import Dict, Optional + + +class AudioFeatureTransform(ABC): + @classmethod + @abstractmethod + def from_config_dict(cls, config: Optional[Dict] = None): + pass + + +AUDIO_FEATURE_TRANSFORM_REGISTRY = {} +AUDIO_FEATURE_TRANSFORM_CLASS_NAMES = set() + + +def register_audio_feature_transform(name): + def register_audio_feature_transform_cls(cls): + if name in AUDIO_FEATURE_TRANSFORM_REGISTRY: + raise ValueError(f"Cannot register duplicate transform ({name})") + if not issubclass(cls, AudioFeatureTransform): + raise ValueError( + f"Transform ({name}: {cls.__name__}) must extend " + "AudioFeatureTransform" + ) + if cls.__name__ in AUDIO_FEATURE_TRANSFORM_CLASS_NAMES: + raise ValueError( + f"Cannot register audio feature transform with duplicate " + f"class name ({cls.__name__})" + ) + AUDIO_FEATURE_TRANSFORM_REGISTRY[name] = cls + AUDIO_FEATURE_TRANSFORM_CLASS_NAMES.add(cls.__name__) + return cls + + return register_audio_feature_transform_cls + + +def get_audio_feature_transform(name): + return AUDIO_FEATURE_TRANSFORM_REGISTRY[name] + + +transforms_dir = os.path.dirname(__file__) +for file in os.listdir(transforms_dir): + path = os.path.join(transforms_dir, file) + if ( + not file.startswith("_") + and not file.startswith(".") + and (file.endswith(".py") or os.path.isdir(path)) + ): + name = file[: file.find(".py")] if file.endswith(".py") else file + importlib.import_module("fairseq.data.audio.feature_transforms." + name) + + +class CompositeAudioFeatureTransform(AudioFeatureTransform): + @classmethod + def from_config_dict(cls, config=None): + _config = {} if config is None else config + _transforms = _config.get("transforms") + if _transforms is None: + return None + transforms = [ + get_audio_feature_transform(_t).from_config_dict(_config.get(_t)) + for _t in _transforms + ] + return CompositeAudioFeatureTransform(transforms) + + def __init__(self, transforms): + self.transforms = [t for t in transforms if t is not None] + + def __call__(self, x): + for t in self.transforms: + x = t(x) + return x + + def __repr__(self): + format_string = ( + [self.__class__.__name__ + "("] + + [f" {t.__repr__()}" for t in self.transforms] + + [")"] + ) + return "\n".join(format_string) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/delta_deltas.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/delta_deltas.py new file mode 100644 index 00000000..49d090b1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/delta_deltas.py @@ -0,0 +1,37 @@ +import numpy as np +import torch +from fairseq.data.audio.feature_transforms import ( + AudioFeatureTransform, + register_audio_feature_transform, +) + + +@register_audio_feature_transform("delta_deltas") +class DeltaDeltas(AudioFeatureTransform): + """Expand delta-deltas features from spectrum.""" + + @classmethod + def from_config_dict(cls, config=None): + _config = {} if config is None else config + return DeltaDeltas(_config.get("win_length", 5)) + + def __init__(self, win_length=5): + self.win_length = win_length + + def __repr__(self): + return self.__class__.__name__ + + def __call__(self, spectrogram): + from torchaudio.functional import compute_deltas + + assert len(spectrogram.shape) == 2, "spectrogram must be a 2-D tensor." + # spectrogram is T x F, while compute_deltas takes (…, F, T) + spectrogram = torch.from_numpy(spectrogram).transpose(0, 1) + delta = compute_deltas(spectrogram) + delta_delta = compute_deltas(delta) + + out_feat = np.concatenate( + [spectrogram, delta.numpy(), delta_delta.numpy()], axis=0 + ) + out_feat = np.transpose(out_feat) + return out_feat diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/global_cmvn.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/global_cmvn.py new file mode 100644 index 00000000..e457ff17 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/global_cmvn.py @@ -0,0 +1,29 @@ +import numpy as np +from fairseq.data.audio.feature_transforms import ( + AudioFeatureTransform, + register_audio_feature_transform, +) + + +@register_audio_feature_transform("global_cmvn") +class GlobalCMVN(AudioFeatureTransform): + """Global CMVN (cepstral mean and variance normalization). The global mean + and variance need to be pre-computed and stored in NumPy format (.npz).""" + + @classmethod + def from_config_dict(cls, config=None): + _config = {} if config is None else config + return GlobalCMVN(_config.get("stats_npz_path")) + + def __init__(self, stats_npz_path): + self.stats_npz_path = stats_npz_path + stats = np.load(stats_npz_path) + self.mean, self.std = stats["mean"], stats["std"] + + def __repr__(self): + return self.__class__.__name__ + f'(stats_npz_path="{self.stats_npz_path}")' + + def __call__(self, x): + x = np.subtract(x, self.mean) + x = np.divide(x, self.std) + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/specaugment.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/specaugment.py new file mode 100644 index 00000000..ce5802b4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/specaugment.py @@ -0,0 +1,131 @@ +import math +import numbers +from typing import Optional + +import numpy as np +from fairseq.data.audio.feature_transforms import ( + AudioFeatureTransform, + register_audio_feature_transform, +) + + +@register_audio_feature_transform("specaugment") +class SpecAugmentTransform(AudioFeatureTransform): + """SpecAugment (https://arxiv.org/abs/1904.08779)""" + + @classmethod + def from_config_dict(cls, config=None): + _config = {} if config is None else config + return SpecAugmentTransform( + _config.get("time_warp_W", 0), + _config.get("freq_mask_N", 0), + _config.get("freq_mask_F", 0), + _config.get("time_mask_N", 0), + _config.get("time_mask_T", 0), + _config.get("time_mask_p", 0.0), + _config.get("mask_value", None), + ) + + def __init__( + self, + time_warp_w: int = 0, + freq_mask_n: int = 0, + freq_mask_f: int = 0, + time_mask_n: int = 0, + time_mask_t: int = 0, + time_mask_p: float = 0.0, + mask_value: Optional[float] = 0.0, + ): + # Sanity checks + assert mask_value is None or isinstance( + mask_value, numbers.Number + ), f"mask_value (type: {type(mask_value)}) must be None or a number" + if freq_mask_n > 0: + assert freq_mask_f > 0, ( + f"freq_mask_F ({freq_mask_f}) " + f"must be larger than 0 when doing freq masking." + ) + if time_mask_n > 0: + assert time_mask_t > 0, ( + f"time_mask_T ({time_mask_t}) must be larger than 0 when " + f"doing time masking." + ) + + self.time_warp_w = time_warp_w + self.freq_mask_n = freq_mask_n + self.freq_mask_f = freq_mask_f + self.time_mask_n = time_mask_n + self.time_mask_t = time_mask_t + self.time_mask_p = time_mask_p + self.mask_value = mask_value + + def __repr__(self): + return ( + self.__class__.__name__ + + "(" + + ", ".join( + [ + f"time_warp_w={self.time_warp_w}", + f"freq_mask_n={self.freq_mask_n}", + f"freq_mask_f={self.freq_mask_f}", + f"time_mask_n={self.time_mask_n}", + f"time_mask_t={self.time_mask_t}", + f"time_mask_p={self.time_mask_p}", + ] + ) + + ")" + ) + + def __call__(self, spectrogram): + assert len(spectrogram.shape) == 2, "spectrogram must be a 2-D tensor." + + distorted = spectrogram.copy() # make a copy of input spectrogram. + num_frames = spectrogram.shape[0] # or 'tau' in the paper. + num_freqs = spectrogram.shape[1] # or 'miu' in the paper. + mask_value = self.mask_value + + if mask_value is None: # if no value was specified, use local mean. + mask_value = spectrogram.mean() + + if num_frames == 0: + return spectrogram + + if num_freqs < self.freq_mask_f: + return spectrogram + + if self.time_warp_w > 0: + if 2 * self.time_warp_w < num_frames: + import cv2 + + w0 = np.random.randint(self.time_warp_w, num_frames - self.time_warp_w) + w = np.random.randint(-self.time_warp_w + 1, self.time_warp_w) + upper, lower = distorted[:w0, :], distorted[w0:, :] + upper = cv2.resize( + upper, dsize=(num_freqs, w0 + w), interpolation=cv2.INTER_LINEAR + ) + lower = cv2.resize( + lower, + dsize=(num_freqs, num_frames - w0 - w), + interpolation=cv2.INTER_LINEAR, + ) + distorted = np.concatenate((upper, lower), axis=0) + + for _i in range(self.freq_mask_n): + f = np.random.randint(0, self.freq_mask_f) + f0 = np.random.randint(0, num_freqs - f) + if f != 0: + distorted[:, f0 : f0 + f] = mask_value + + max_time_mask_t = min( + self.time_mask_t, math.floor(num_frames * self.time_mask_p) + ) + if max_time_mask_t < 1: + return distorted + + for _i in range(self.time_mask_n): + t = np.random.randint(0, max_time_mask_t) + t0 = np.random.randint(0, num_frames - t) + if t != 0: + distorted[t0 : t0 + t, :] = mask_value + + return distorted diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/utterance_cmvn.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/utterance_cmvn.py new file mode 100644 index 00000000..37637bc0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/feature_transforms/utterance_cmvn.py @@ -0,0 +1,41 @@ +import numpy as np + +from fairseq.data.audio.feature_transforms import ( + AudioFeatureTransform, + register_audio_feature_transform, +) + + +@register_audio_feature_transform("utterance_cmvn") +class UtteranceCMVN(AudioFeatureTransform): + """Utterance-level CMVN (cepstral mean and variance normalization)""" + + @classmethod + def from_config_dict(cls, config=None): + _config = {} if config is None else config + return UtteranceCMVN( + _config.get("norm_means", True), + _config.get("norm_vars", True), + ) + + def __init__(self, norm_means=True, norm_vars=True): + self.norm_means, self.norm_vars = norm_means, norm_vars + + def __repr__(self): + return ( + self.__class__.__name__ + + f"(norm_means={self.norm_means}, norm_vars={self.norm_vars})" + ) + + def __call__(self, x): + mean = x.mean(axis=0) + square_sums = (x**2).sum(axis=0) + + if self.norm_means: + x = np.subtract(x, mean) + if self.norm_vars: + var = square_sums / x.shape[0] - mean**2 + std = np.sqrt(np.maximum(var, 1e-10)) + x = np.divide(x, std) + + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/frm_text_to_speech_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/frm_text_to_speech_dataset.py new file mode 100644 index 00000000..b54654d4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/frm_text_to_speech_dataset.py @@ -0,0 +1,205 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory.abs + +import csv +import logging +import os.path as op +from typing import List, Optional + +import numpy as np +import torch +from fairseq.data import Dictionary +from fairseq.data.audio.speech_to_text_dataset import S2TDataConfig +from fairseq.data.audio.text_to_speech_dataset import ( + TextToSpeechDataset, + TextToSpeechDatasetCreator, +) + +logger = logging.getLogger(__name__) + + +class FrmTextToSpeechDataset(TextToSpeechDataset): + def __init__( + self, + split: str, + is_train_split: bool, + data_cfg: S2TDataConfig, + audio_paths: List[str], + n_frames: List[int], + src_texts: Optional[List[str]] = None, + tgt_texts: Optional[List[str]] = None, + speakers: Optional[List[str]] = None, + src_langs: Optional[List[str]] = None, + tgt_langs: Optional[List[str]] = None, + ids: Optional[List[str]] = None, + tgt_dict: Optional[Dictionary] = None, + pre_tokenizer=None, + bpe_tokenizer=None, + n_frames_per_step=1, + speaker_to_id=None, + do_chunk=False, + chunk_bound=-1, + chunk_init=50, + chunk_incr=5, + add_eos=True, + dedup=True, + ref_fpu=-1, + ): + # It assumes texts are encoded at a fixed frame-rate + super().__init__( + split=split, + is_train_split=is_train_split, + data_cfg=data_cfg, + audio_paths=audio_paths, + n_frames=n_frames, + src_texts=src_texts, + tgt_texts=tgt_texts, + speakers=speakers, + src_langs=src_langs, + tgt_langs=tgt_langs, + ids=ids, + tgt_dict=tgt_dict, + pre_tokenizer=pre_tokenizer, + bpe_tokenizer=bpe_tokenizer, + n_frames_per_step=n_frames_per_step, + speaker_to_id=speaker_to_id, + ) + + self.do_chunk = do_chunk + self.chunk_bound = chunk_bound + self.chunk_init = chunk_init + self.chunk_incr = chunk_incr + self.add_eos = add_eos + self.dedup = dedup + self.ref_fpu = ref_fpu + + self.chunk_size = -1 + + if do_chunk: + assert self.chunk_incr >= 0 + assert self.pre_tokenizer is None + + def __getitem__(self, index): + index, source, target, speaker_id, _, _, _ = super().__getitem__(index) + if target[-1].item() == self.tgt_dict.eos_index: + target = target[:-1] + + fpu = source.size(0) / target.size(0) # frame-per-unit + fps = self.n_frames_per_step + assert ( + self.ref_fpu == -1 or abs((fpu * fps - self.ref_fpu) / self.ref_fpu) < 0.1 + ), f"{fpu*fps} != {self.ref_fpu}" + + # only chunk training split + if self.is_train_split and self.do_chunk and self.chunk_size > 0: + lang = target[: int(self.data_cfg.prepend_tgt_lang_tag)] + text = target[int(self.data_cfg.prepend_tgt_lang_tag) :] + size = len(text) + chunk_size = min(self.chunk_size, size) + chunk_start = np.random.randint(size - chunk_size + 1) + text = text[chunk_start : chunk_start + chunk_size] + target = torch.cat((lang, text), 0) + + f_size = int(np.floor(chunk_size * fpu)) + f_start = int(np.floor(chunk_start * fpu)) + assert f_size > 0 + source = source[f_start : f_start + f_size, :] + + if self.dedup: + target = torch.unique_consecutive(target) + + if self.add_eos: + eos_idx = self.tgt_dict.eos_index + target = torch.cat((target, torch.LongTensor([eos_idx])), 0) + + return index, source, target, speaker_id + + def set_epoch(self, epoch): + if self.is_train_split and self.do_chunk: + old = self.chunk_size + self.chunk_size = self.chunk_init + epoch * self.chunk_incr + if self.chunk_bound > 0: + self.chunk_size = min(self.chunk_size, self.chunk_bound) + logger.info( + ( + f"{self.split}: setting chunk size " + f"from {old} to {self.chunk_size}" + ) + ) + + +class FrmTextToSpeechDatasetCreator(TextToSpeechDatasetCreator): + # inherit for key names + @classmethod + def from_tsv( + cls, + root: str, + data_cfg: S2TDataConfig, + split: str, + tgt_dict, + pre_tokenizer, + bpe_tokenizer, + is_train_split: bool, + n_frames_per_step: int, + speaker_to_id, + do_chunk: bool = False, + chunk_bound: int = -1, + chunk_init: int = 50, + chunk_incr: int = 5, + add_eos: bool = True, + dedup: bool = True, + ref_fpu: float = -1, + ) -> FrmTextToSpeechDataset: + tsv_path = op.join(root, f"{split}.tsv") + if not op.isfile(tsv_path): + raise FileNotFoundError(f"Dataset not found: {tsv_path}") + with open(tsv_path) as f: + reader = csv.DictReader( + f, + delimiter="\t", + quotechar=None, + doublequote=False, + lineterminator="\n", + quoting=csv.QUOTE_NONE, + ) + s = [dict(e) for e in reader] + assert len(s) > 0 + + ids = [ss[cls.KEY_ID] for ss in s] + audio_paths = [op.join(data_cfg.audio_root, ss[cls.KEY_AUDIO]) for ss in s] + n_frames = [int(ss[cls.KEY_N_FRAMES]) for ss in s] + tgt_texts = [ss[cls.KEY_TGT_TEXT] for ss in s] + src_texts = [ss.get(cls.KEY_SRC_TEXT, cls.DEFAULT_SRC_TEXT) for ss in s] + speakers = [ss.get(cls.KEY_SPEAKER, cls.DEFAULT_SPEAKER) for ss in s] + src_langs = [ss.get(cls.KEY_SRC_LANG, cls.DEFAULT_LANG) for ss in s] + tgt_langs = [ss.get(cls.KEY_TGT_LANG, cls.DEFAULT_LANG) for ss in s] + + return FrmTextToSpeechDataset( + split=split, + is_train_split=is_train_split, + data_cfg=data_cfg, + audio_paths=audio_paths, + n_frames=n_frames, + src_texts=src_texts, + tgt_texts=tgt_texts, + speakers=speakers, + src_langs=src_langs, + tgt_langs=tgt_langs, + ids=ids, + tgt_dict=tgt_dict, + pre_tokenizer=pre_tokenizer, + bpe_tokenizer=bpe_tokenizer, + n_frames_per_step=n_frames_per_step, + speaker_to_id=speaker_to_id, + do_chunk=do_chunk, + chunk_bound=chunk_bound, + chunk_init=chunk_init, + chunk_incr=chunk_incr, + add_eos=add_eos, + dedup=dedup, + ref_fpu=ref_fpu, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/hubert_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/hubert_dataset.py new file mode 100644 index 00000000..a69b7dc9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/hubert_dataset.py @@ -0,0 +1,344 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import itertools +import logging +import os +import sys +from typing import Any, List, Optional, Union + +import numpy as np + +import torch +import torch.nn.functional as F +from fairseq.data import data_utils +from fairseq.data.fairseq_dataset import FairseqDataset + +logger = logging.getLogger(__name__) + + +def load_audio(manifest_path, max_keep, min_keep): + n_long, n_short = 0, 0 + names, inds, sizes = [], [], [] + with open(manifest_path) as f: + root = f.readline().strip() + for ind, line in enumerate(f): + items = line.strip().split("\t") + assert len(items) == 2, line + sz = int(items[1]) + if min_keep is not None and sz < min_keep: + n_short += 1 + elif max_keep is not None and sz > max_keep: + n_long += 1 + else: + names.append(items[0]) + inds.append(ind) + sizes.append(sz) + tot = ind + 1 + logger.info( + ( + f"max_keep={max_keep}, min_keep={min_keep}, " + f"loaded {len(names)}, skipped {n_short} short and {n_long} long, " + f"longest-loaded={max(sizes)}, shortest-loaded={min(sizes)}" + ) + ) + return root, names, inds, tot, sizes + + +def load_label(label_path, inds, tot): + with open(label_path) as f: + labels = [line.rstrip() for line in f] + assert ( + len(labels) == tot + ), f"number of labels does not match ({len(labels)} != {tot})" + labels = [labels[i] for i in inds] + return labels + + +def load_label_offset(label_path, inds, tot): + with open(label_path) as f: + code_lengths = [len(line.encode("utf-8")) for line in f] + assert ( + len(code_lengths) == tot + ), f"number of labels does not match ({len(code_lengths)} != {tot})" + offsets = list(itertools.accumulate([0] + code_lengths)) + offsets = [(offsets[i], offsets[i + 1]) for i in inds] + return offsets + + +def verify_label_lengths( + audio_sizes, + audio_rate, + label_path, + label_rate, + inds, + tot, + tol=0.1, # tolerance in seconds +): + if label_rate < 0: + logger.info(f"{label_path} is sequence label. skipped") + return + + with open(label_path) as f: + lengths = [len(line.rstrip().split()) for line in f] + assert len(lengths) == tot + lengths = [lengths[i] for i in inds] + num_invalid = 0 + for i, ind in enumerate(inds): + dur_from_audio = audio_sizes[i] / audio_rate + dur_from_label = lengths[i] / label_rate + if abs(dur_from_audio - dur_from_label) > tol: + logger.warning( + ( + f"audio and label duration differ too much " + f"(|{dur_from_audio} - {dur_from_label}| > {tol}) " + f"in line {ind+1} of {label_path}. Check if `label_rate` " + f"is correctly set (currently {label_rate}). " + f"num. of samples = {audio_sizes[i]}; " + f"label length = {lengths[i]}" + ) + ) + num_invalid += 1 + if num_invalid > 0: + logger.warning( + f"total {num_invalid} (audio, label) pairs with mismatched lengths" + ) + + +class HubertDataset(FairseqDataset): + def __init__( + self, + manifest_path: str, + sample_rate: float, + label_paths: List[str], + label_rates: Union[List[float], float], # -1 for sequence labels + pad_list: List[str], + eos_list: List[str], + label_processors: Optional[List[Any]] = None, + max_keep_sample_size: Optional[int] = None, + min_keep_sample_size: Optional[int] = None, + max_sample_size: Optional[int] = None, + shuffle: bool = True, + pad_audio: bool = False, + normalize: bool = False, + store_labels: bool = True, + random_crop: bool = False, + single_target: bool = False, + ): + self.audio_root, self.audio_names, inds, tot, self.sizes = load_audio( + manifest_path, max_keep_sample_size, min_keep_sample_size + ) + self.sample_rate = sample_rate + self.shuffle = shuffle + self.random_crop = random_crop + + self.num_labels = len(label_paths) + self.pad_list = pad_list + self.eos_list = eos_list + self.label_processors = label_processors + self.single_target = single_target + self.label_rates = ( + [label_rates for _ in range(len(label_paths))] + if isinstance(label_rates, float) + else label_rates + ) + self.store_labels = store_labels + if store_labels: + self.label_list = [load_label(p, inds, tot) for p in label_paths] + else: + self.label_paths = label_paths + self.label_offsets_list = [ + load_label_offset(p, inds, tot) for p in label_paths + ] + assert label_processors is None or len(label_processors) == self.num_labels + for label_path, label_rate in zip(label_paths, self.label_rates): + verify_label_lengths( + self.sizes, sample_rate, label_path, label_rate, inds, tot + ) + + self.max_sample_size = ( + max_sample_size if max_sample_size is not None else sys.maxsize + ) + self.pad_audio = pad_audio + self.normalize = normalize + logger.info( + f"pad_audio={pad_audio}, random_crop={random_crop}, " + f"normalize={normalize}, max_sample_size={self.max_sample_size}" + ) + + def get_audio(self, index): + import soundfile as sf + + wav_path = os.path.join(self.audio_root, self.audio_names[index]) + wav, cur_sample_rate = sf.read(wav_path) + wav = torch.from_numpy(wav).float() + wav = self.postprocess(wav, cur_sample_rate) + return wav + + def get_label(self, index, label_idx): + if self.store_labels: + label = self.label_list[label_idx][index] + else: + with open(self.label_paths[label_idx]) as f: + offset_s, offset_e = self.label_offsets_list[label_idx][index] + f.seek(offset_s) + label = f.read(offset_e - offset_s) + + if self.label_processors is not None: + label = self.label_processors[label_idx](label) + return label + + def get_labels(self, index): + return [self.get_label(index, i) for i in range(self.num_labels)] + + def __getitem__(self, index): + wav = self.get_audio(index) + labels = self.get_labels(index) + return {"id": index, "source": wav, "label_list": labels} + + def __len__(self): + return len(self.sizes) + + def crop_to_max_size(self, wav, target_size): + size = len(wav) + diff = size - target_size + if diff <= 0: + return wav, 0 + + start, end = 0, target_size + if self.random_crop: + start = np.random.randint(0, diff + 1) + end = size - diff + start + return wav[start:end], start + + def collater(self, samples): + # target = max(sizes) -> random_crop not used + # target = max_sample_size -> random_crop used for long + samples = [s for s in samples if s["source"] is not None] + if len(samples) == 0: + return {} + + audios = [s["source"] for s in samples] + audio_sizes = [len(s) for s in audios] + if self.pad_audio: + audio_size = min(max(audio_sizes), self.max_sample_size) + else: + audio_size = min(min(audio_sizes), self.max_sample_size) + collated_audios, padding_mask, audio_starts = self.collater_audio( + audios, audio_size + ) + + targets_by_label = [ + [s["label_list"][i] for s in samples] for i in range(self.num_labels) + ] + targets_list, lengths_list, ntokens_list = self.collater_label( + targets_by_label, audio_size, audio_starts + ) + + net_input = {"source": collated_audios, "padding_mask": padding_mask} + batch = { + "id": torch.LongTensor([s["id"] for s in samples]), + "net_input": net_input, + } + + if self.single_target: + batch["target_lengths"] = lengths_list[0] + batch["ntokens"] = ntokens_list[0] + batch["target"] = targets_list[0] + else: + batch["target_lengths_list"] = lengths_list + batch["ntokens_list"] = ntokens_list + batch["target_list"] = targets_list + return batch + + def collater_audio(self, audios, audio_size): + collated_audios = audios[0].new_zeros(len(audios), audio_size) + padding_mask = ( + torch.BoolTensor(collated_audios.shape).fill_(False) + # if self.pad_audio else None + ) + audio_starts = [0 for _ in audios] + for i, audio in enumerate(audios): + diff = len(audio) - audio_size + if diff == 0: + collated_audios[i] = audio + elif diff < 0: + assert self.pad_audio + collated_audios[i] = torch.cat([audio, audio.new_full((-diff,), 0.0)]) + padding_mask[i, diff:] = True + else: + collated_audios[i], audio_starts[i] = self.crop_to_max_size( + audio, audio_size + ) + return collated_audios, padding_mask, audio_starts + + def collater_frm_label(self, targets, audio_size, audio_starts, label_rate, pad): + assert label_rate > 0 + s2f = label_rate / self.sample_rate + frm_starts = [int(round(s * s2f)) for s in audio_starts] + frm_size = int(round(audio_size * s2f)) + if not self.pad_audio: + rem_size = [len(t) - s for t, s in zip(targets, frm_starts)] + frm_size = min(frm_size, *rem_size) + targets = [t[s : s + frm_size] for t, s in zip(targets, frm_starts)] + logger.debug(f"audio_starts={audio_starts}") + logger.debug(f"frame_starts={frm_starts}") + logger.debug(f"frame_size={frm_size}") + + lengths = torch.LongTensor([len(t) for t in targets]) + ntokens = lengths.sum().item() + targets = data_utils.collate_tokens(targets, pad_idx=pad, left_pad=False) + return targets, lengths, ntokens + + def collater_seq_label(self, targets, pad): + lengths = torch.LongTensor([len(t) for t in targets]) + ntokens = lengths.sum().item() + targets = data_utils.collate_tokens(targets, pad_idx=pad, left_pad=False) + return targets, lengths, ntokens + + def collater_label(self, targets_by_label, audio_size, audio_starts): + targets_list, lengths_list, ntokens_list = [], [], [] + itr = zip(targets_by_label, self.label_rates, self.pad_list) + for targets, label_rate, pad in itr: + if label_rate == -1.0: + targets, lengths, ntokens = self.collater_seq_label(targets, pad) + else: + targets, lengths, ntokens = self.collater_frm_label( + targets, audio_size, audio_starts, label_rate, pad + ) + targets_list.append(targets) + lengths_list.append(lengths) + ntokens_list.append(ntokens) + return targets_list, lengths_list, ntokens_list + + def num_tokens(self, index): + return self.size(index) + + def size(self, index): + if self.pad_audio: + return self.sizes[index] + return min(self.sizes[index], self.max_sample_size) + + def ordered_indices(self): + if self.shuffle: + order = [np.random.permutation(len(self))] + else: + order = [np.arange(len(self))] + + order.append(self.sizes) + return np.lexsort(order)[::-1] + + def postprocess(self, wav, cur_sample_rate): + if wav.dim() == 2: + wav = wav.mean(-1) + assert wav.dim() == 1, wav.dim() + + if cur_sample_rate != self.sample_rate: + raise Exception(f"sr {cur_sample_rate} != {self.sample_rate}") + + if self.normalize: + with torch.no_grad(): + wav = F.layer_norm(wav, wav.shape) + return wav diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/multi_modality_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/multi_modality_dataset.py new file mode 100644 index 00000000..39551a61 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/multi_modality_dataset.py @@ -0,0 +1,266 @@ +# Copyright (c) 2021-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + +import logging +import math +from typing import List, Optional, NamedTuple + +import numpy as np +import torch +from fairseq.data import ( + ConcatDataset, + LanguagePairDataset, + FileAudioDataset, + data_utils, +) +from fairseq.data import FairseqDataset + +logger = logging.getLogger(__name__) + + +class ModalityDatasetItem(NamedTuple): + datasetname: str + dataset: any + max_positions: List[int] + max_tokens: Optional[int] = None + max_sentences: Optional[int] = None + + +# MultiModalityDataset: it concate multiple datasets with different modalities. +# Compared with ConcatDataset it can 1) sample data given the ratios for different datasets +# 2) it adds mode to indicate what type of the data samples come from. +# It will be used with GroupedEpochBatchIterator together to generate mini-batch with samples +# from the same type of dataset +# If only one dataset is used, it will perform like the original dataset with mode added +class MultiModalityDataset(ConcatDataset): + def __init__(self, datasets: List[ModalityDatasetItem]): + id_to_mode = [] + dsets = [] + max_tokens = [] + max_sentences = [] + max_positions = [] + for dset in datasets: + id_to_mode.append(dset.datasetname) + dsets.append(dset.dataset) + max_tokens.append(dset.max_tokens) + max_positions.append(dset.max_positions) + max_sentences.append(dset.max_sentences) + weights = [1.0 for s in dsets] + super().__init__(dsets, weights) + self.max_tokens = max_tokens + self.max_positions = max_positions + self.max_sentences = max_sentences + self.id_to_mode = id_to_mode + self.raw_sub_batch_samplers = [] + self._cur_epoch = 0 + + def set_epoch(self, epoch): + super().set_epoch(epoch) + self._cur_epoch = epoch + + def __getitem__(self, idx): + dataset_idx, sample_idx = self._get_dataset_and_sample_index(idx) + sample = self.datasets[dataset_idx][sample_idx] + return (dataset_idx, sample) + + def collater(self, samples): + if len(samples) == 0: + return {} + dataset_idx = samples[0][0] + # make sure all samples in samples are from same dataset + assert sum([0 if dataset_idx == s[0] else 1 for s in samples]) == 0 + samples = self.datasets[dataset_idx].collater([x[1] for x in samples]) + # add mode + samples["net_input"]["mode"] = self.id_to_mode[dataset_idx] + + return samples + + def size(self, index: int): + if len(self.datasets) == 1: + return self.datasets[0].size(index) + return super().size(index) + + @property + def sizes(self): + if len(self.datasets) == 1: + return self.datasets[0].sizes + super().sizes + + def ordered_indices(self): + """ + Returns indices sorted by length. So less padding is needed. + """ + if len(self.datasets) == 1: + return self.datasets[0].ordered_indices() + indices_group = [] + for d_idx, ds in enumerate(self.datasets): + sample_num = self.cumulative_sizes[d_idx] + if d_idx > 0: + sample_num = sample_num - self.cumulative_sizes[d_idx - 1] + assert sample_num == len(ds) + indices_group.append(ds.ordered_indices()) + return indices_group + + def get_raw_batch_samplers(self, required_batch_size_multiple, seed): + if len(self.raw_sub_batch_samplers) > 0: + logger.info(" raw_sub_batch_samplers exists. No action is taken") + return + with data_utils.numpy_seed(seed): + indices = self.ordered_indices() + for i, ds in enumerate(self.datasets): + indices[i] = ds.filter_indices_by_size( + indices[i], + self.max_positions[i], + )[0] + sub_batch_sampler = ds.batch_by_size( + indices[i], + max_tokens=self.max_tokens[i], + max_sentences=self.max_sentences[i], + required_batch_size_multiple=required_batch_size_multiple, + ) + self.raw_sub_batch_samplers.append(sub_batch_sampler) + + def get_batch_samplers(self, mult_ratios, required_batch_size_multiple, seed): + self.get_raw_batch_samplers(required_batch_size_multiple, seed) + batch_samplers = [] + for i, _ in enumerate(self.datasets): + if i > 0: + sub_batch_sampler = [ + [y + self.cumulative_sizes[i - 1] for y in x] + for x in self.raw_sub_batch_samplers[i] + ] + else: + sub_batch_sampler = list(self.raw_sub_batch_samplers[i]) + smp_r = mult_ratios[i] + if smp_r != 1: + is_increase = "increased" if smp_r > 1 else "decreased" + logger.info( + "number of batch for the dataset {} is {} from {} to {}".format( + self.id_to_mode[i], + is_increase, + len(sub_batch_sampler), + int(len(sub_batch_sampler) * smp_r), + ) + ) + mul_samplers = [] + for _ in range(math.floor(smp_r)): + mul_samplers = mul_samplers + sub_batch_sampler + if math.floor(smp_r) != smp_r: + with data_utils.numpy_seed(seed + self._cur_epoch): + np.random.shuffle(sub_batch_sampler) + smp_num = int( + (smp_r - math.floor(smp_r)) * len(sub_batch_sampler) + ) + mul_samplers = mul_samplers + sub_batch_sampler[:smp_num] + sub_batch_sampler = mul_samplers + else: + logger.info( + "dataset {} batch number is {} ".format( + self.id_to_mode[i], len(sub_batch_sampler) + ) + ) + batch_samplers.append(sub_batch_sampler) + + return batch_samplers + + +class LangPairMaskDataset(FairseqDataset): + def __init__( + self, + dataset: LanguagePairDataset, + src_eos: int, + src_bos: Optional[int] = None, + noise_id: Optional[int] = -1, + mask_ratio: Optional[float] = 0, + mask_type: Optional[str] = "random", + ): + self.dataset = dataset + self.src_eos = src_eos + self.src_bos = src_bos + self.noise_id = noise_id + self.mask_ratio = mask_ratio + self.mask_type = mask_type + assert mask_type in ("random", "tail") + + @property + def src_sizes(self): + return self.dataset.src_sizes + + @property + def tgt_sizes(self): + return self.dataset.tgt_sizes + + @property + def sizes(self): + # dataset.sizes can be a dynamically computed sizes: + return self.dataset.sizes + + def get_batch_shapes(self): + if hasattr(self.dataset, "get_batch_shapes"): + return self.dataset.get_batch_shapes() + return self.dataset.buckets + + def num_tokens_vec(self, indices): + return self.dataset.num_tokens_vec(indices) + + def __len__(self): + return len(self.dataset) + + def num_tokens(self, index): + return self.dataset.num_tokens(index) + + def size(self, index): + return self.dataset.size(index) + + def ordered_indices(self): + return self.dataset.ordered_indices() + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def prefetch(self, indices): + return self.dataset.prefetch(indices) + + def mask_src_tokens(self, sample): + src_item = sample["source"] + mask = None + if self.mask_type == "random": + mask = torch.rand(len(src_item)).le(self.mask_ratio) + else: + mask = torch.ones(len(src_item)) + mask[: int(len(src_item) * (1 - self.mask_ratio))] = 0 + mask = mask.eq(1) + if src_item[0] == self.src_bos: + mask[0] = False + if src_item[-1] == self.src_eos: + mask[-1] = False + mask_src_item = src_item.masked_fill(mask, self.noise_id) + smp = {"id": sample["id"], "source": mask_src_item, "target": sample["target"]} + return smp + + def __getitem__(self, index): + sample = self.dataset[index] + if self.mask_ratio > 0: + sample = self.mask_src_tokens(sample) + return sample + + def collater(self, samples, pad_to_length=None): + return self.dataset.collater(samples, pad_to_length) + + +class FileAudioDatasetWrapper(FileAudioDataset): + def collater(self, samples): + samples = super().collater(samples) + if len(samples) == 0: + return {} + samples["net_input"]["src_tokens"] = samples["net_input"]["source"] + samples["net_input"]["prev_output_tokens"] = None + del samples["net_input"]["source"] + samples["net_input"]["src_lengths"] = None + samples["net_input"]["alignment"] = None + return samples diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/raw_audio_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/raw_audio_dataset.py new file mode 100644 index 00000000..181e2bbc --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/raw_audio_dataset.py @@ -0,0 +1,393 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +import logging +import os +import sys +import io + +import numpy as np +import torch +import torch.nn.functional as F + +from .. import FairseqDataset +from ..data_utils import compute_mask_indices, get_buckets, get_bucketed_sizes +from fairseq.data.audio.audio_utils import ( + parse_path, + read_from_stored_zip, + is_sf_audio_data, +) +from fairseq.data.text_compressor import TextCompressor, TextCompressionLevel + + +logger = logging.getLogger(__name__) + + +class RawAudioDataset(FairseqDataset): + def __init__( + self, + sample_rate, + max_sample_size=None, + min_sample_size=0, + shuffle=True, + pad=False, + normalize=False, + compute_mask_indices=False, + **mask_compute_kwargs, + ): + super().__init__() + + self.sample_rate = sample_rate + self.sizes = [] + self.max_sample_size = ( + max_sample_size if max_sample_size is not None else sys.maxsize + ) + self.min_sample_size = min_sample_size + self.pad = pad + self.shuffle = shuffle + self.normalize = normalize + self.compute_mask_indices = compute_mask_indices + if self.compute_mask_indices: + self.mask_compute_kwargs = mask_compute_kwargs + self._features_size_map = {} + self._C = mask_compute_kwargs["encoder_embed_dim"] + self._conv_feature_layers = eval(mask_compute_kwargs["conv_feature_layers"]) + + def __getitem__(self, index): + raise NotImplementedError() + + def __len__(self): + return len(self.sizes) + + def postprocess(self, feats, curr_sample_rate): + if feats.dim() == 2: + feats = feats.mean(-1) + + if curr_sample_rate != self.sample_rate: + raise Exception(f"sample rate: {curr_sample_rate}, need {self.sample_rate}") + + assert feats.dim() == 1, feats.dim() + + if self.normalize: + with torch.no_grad(): + feats = F.layer_norm(feats, feats.shape) + return feats + + def crop_to_max_size(self, wav, target_size): + size = len(wav) + diff = size - target_size + if diff <= 0: + return wav + + start = np.random.randint(0, diff + 1) + end = size - diff + start + return wav[start:end] + + def _compute_mask_indices(self, dims, padding_mask): + B, T, C = dims + mask_indices, mask_channel_indices = None, None + if self.mask_compute_kwargs["mask_prob"] > 0: + mask_indices = compute_mask_indices( + (B, T), + padding_mask, + self.mask_compute_kwargs["mask_prob"], + self.mask_compute_kwargs["mask_length"], + self.mask_compute_kwargs["mask_selection"], + self.mask_compute_kwargs["mask_other"], + min_masks=2, + no_overlap=self.mask_compute_kwargs["no_mask_overlap"], + min_space=self.mask_compute_kwargs["mask_min_space"], + ) + mask_indices = torch.from_numpy(mask_indices) + if self.mask_compute_kwargs["mask_channel_prob"] > 0: + mask_channel_indices = compute_mask_indices( + (B, C), + None, + self.mask_compute_kwargs["mask_channel_prob"], + self.mask_compute_kwargs["mask_channel_length"], + self.mask_compute_kwargs["mask_channel_selection"], + self.mask_compute_kwargs["mask_channel_other"], + no_overlap=self.mask_compute_kwargs["no_mask_channel_overlap"], + min_space=self.mask_compute_kwargs["mask_channel_min_space"], + ) + mask_channel_indices = ( + torch.from_numpy(mask_channel_indices).unsqueeze(1).expand(-1, T, -1) + ) + + return mask_indices, mask_channel_indices + + @staticmethod + def _bucket_tensor(tensor, num_pad, value): + return F.pad(tensor, (0, num_pad), value=value) + + def collater(self, samples): + samples = [s for s in samples if s["source"] is not None] + if len(samples) == 0: + return {} + + sources = [s["source"] for s in samples] + sizes = [len(s) for s in sources] + + if self.pad: + target_size = min(max(sizes), self.max_sample_size) + else: + target_size = min(min(sizes), self.max_sample_size) + + collated_sources = sources[0].new_zeros(len(sources), target_size) + padding_mask = ( + torch.BoolTensor(collated_sources.shape).fill_(False) if self.pad else None + ) + for i, (source, size) in enumerate(zip(sources, sizes)): + diff = size - target_size + if diff == 0: + collated_sources[i] = source + elif diff < 0: + assert self.pad + collated_sources[i] = torch.cat( + [source, source.new_full((-diff,), 0.0)] + ) + padding_mask[i, diff:] = True + else: + collated_sources[i] = self.crop_to_max_size(source, target_size) + + input = {"source": collated_sources} + out = {"id": torch.LongTensor([s["id"] for s in samples])} + if self.pad: + input["padding_mask"] = padding_mask + + if hasattr(self, "num_buckets") and self.num_buckets > 0: + assert self.pad, "Cannot bucket without padding first." + bucket = max(self._bucketed_sizes[s["id"]] for s in samples) + num_pad = bucket - collated_sources.size(-1) + if num_pad: + input["source"] = self._bucket_tensor(collated_sources, num_pad, 0) + input["padding_mask"] = self._bucket_tensor(padding_mask, num_pad, True) + + if self.compute_mask_indices: + B = input["source"].size(0) + T = self._get_mask_indices_dims(input["source"].size(-1)) + padding_mask_reshaped = input["padding_mask"].clone() + extra = padding_mask_reshaped.size(1) % T + if extra > 0: + padding_mask_reshaped = padding_mask_reshaped[:, :-extra] + padding_mask_reshaped = padding_mask_reshaped.view( + padding_mask_reshaped.size(0), T, -1 + ) + padding_mask_reshaped = padding_mask_reshaped.all(-1) + input["padding_count"] = padding_mask_reshaped.sum(-1).max().item() + mask_indices, mask_channel_indices = self._compute_mask_indices( + (B, T, self._C), + padding_mask_reshaped, + ) + input["mask_indices"] = mask_indices + input["mask_channel_indices"] = mask_channel_indices + out["sample_size"] = mask_indices.sum().item() + + out["net_input"] = input + return out + + def _get_mask_indices_dims(self, size, padding=0, dilation=1): + if size not in self._features_size_map: + L_in = size + for (_, kernel_size, stride) in self._conv_feature_layers: + L_out = L_in + 2 * padding - dilation * (kernel_size - 1) - 1 + L_out = 1 + L_out // stride + L_in = L_out + self._features_size_map[size] = L_out + return self._features_size_map[size] + + def num_tokens(self, index): + return self.size(index) + + def size(self, index): + """Return an example's size as a float or tuple. This value is used when + filtering a dataset with ``--max-positions``.""" + if self.pad: + return self.sizes[index] + return min(self.sizes[index], self.max_sample_size) + + def ordered_indices(self): + """Return an ordered list of indices. Batches will be constructed based + on this order.""" + + if self.shuffle: + order = [np.random.permutation(len(self))] + order.append( + np.minimum( + np.array(self.sizes), + self.max_sample_size, + ) + ) + return np.lexsort(order)[::-1] + else: + return np.arange(len(self)) + + def set_bucket_info(self, num_buckets): + self.num_buckets = num_buckets + if self.num_buckets > 0: + self._collated_sizes = np.minimum( + np.array(self.sizes), + self.max_sample_size, + ) + self.buckets = get_buckets( + self._collated_sizes, + self.num_buckets, + ) + self._bucketed_sizes = get_bucketed_sizes( + self._collated_sizes, self.buckets + ) + logger.info( + f"{len(self.buckets)} bucket(s) for the audio dataset: " + f"{self.buckets}" + ) + + +class FileAudioDataset(RawAudioDataset): + def __init__( + self, + manifest_path, + sample_rate, + max_sample_size=None, + min_sample_size=0, + shuffle=True, + pad=False, + normalize=False, + num_buckets=0, + compute_mask_indices=False, + text_compression_level=TextCompressionLevel.none, + **mask_compute_kwargs, + ): + super().__init__( + sample_rate=sample_rate, + max_sample_size=max_sample_size, + min_sample_size=min_sample_size, + shuffle=shuffle, + pad=pad, + normalize=normalize, + compute_mask_indices=compute_mask_indices, + **mask_compute_kwargs, + ) + + self.text_compressor = TextCompressor(level=text_compression_level) + + skipped = 0 + self.fnames = [] + sizes = [] + self.skipped_indices = set() + + with open(manifest_path, "r") as f: + self.root_dir = f.readline().strip() + for i, line in enumerate(f): + items = line.strip().split("\t") + assert len(items) == 2, line + sz = int(items[1]) + if min_sample_size is not None and sz < min_sample_size: + skipped += 1 + self.skipped_indices.add(i) + continue + self.fnames.append(self.text_compressor.compress(items[0])) + sizes.append(sz) + logger.info(f"loaded {len(self.fnames)}, skipped {skipped} samples") + + self.sizes = np.array(sizes, dtype=np.int64) + + try: + import pyarrow + + self.fnames = pyarrow.array(self.fnames) + except: + logger.debug( + "Could not create a pyarrow array. Please install pyarrow for better performance" + ) + pass + + self.set_bucket_info(num_buckets) + + def __getitem__(self, index): + import soundfile as sf + + fn = self.fnames[index] + fn = fn if isinstance(self.fnames, list) else fn.as_py() + fn = self.text_compressor.decompress(fn) + path_or_fp = os.path.join(self.root_dir, fn) + _path, slice_ptr = parse_path(path_or_fp) + if len(slice_ptr) == 2: + byte_data = read_from_stored_zip(_path, slice_ptr[0], slice_ptr[1]) + assert is_sf_audio_data(byte_data) + path_or_fp = io.BytesIO(byte_data) + + wav, curr_sample_rate = sf.read(path_or_fp, dtype="float32") + + feats = torch.from_numpy(wav).float() + feats = self.postprocess(feats, curr_sample_rate) + return {"id": index, "source": feats} + + +class BinarizedAudioDataset(RawAudioDataset): + def __init__( + self, + data_dir, + split, + sample_rate, + max_sample_size=None, + min_sample_size=0, + shuffle=True, + pad=False, + normalize=False, + num_buckets=0, + compute_mask_indices=False, + **mask_compute_kwargs, + ): + super().__init__( + sample_rate=sample_rate, + max_sample_size=max_sample_size, + min_sample_size=min_sample_size, + shuffle=shuffle, + pad=pad, + normalize=normalize, + compute_mask_indices=compute_mask_indices, + **mask_compute_kwargs, + ) + + from fairseq.data import data_utils, Dictionary + + self.fnames_dict = Dictionary.load(os.path.join(data_dir, "dict.txt")) + + root_path = os.path.join(data_dir, f"{split}.root") + if os.path.exists(root_path): + with open(root_path, "r") as f: + self.root_dir = next(f).strip() + else: + self.root_dir = None + + fnames_path = os.path.join(data_dir, split) + self.fnames = data_utils.load_indexed_dataset(fnames_path, self.fnames_dict) + lengths_path = os.path.join(data_dir, f"{split}.lengths") + + with open(lengths_path, "r") as f: + for line in f: + sz = int(line.rstrip()) + assert ( + sz >= min_sample_size + ), f"Min sample size is not supported for binarized dataset, but found a sample with size {sz}" + self.sizes.append(sz) + + self.sizes = np.array(self.sizes, dtype=np.int64) + + self.set_bucket_info(num_buckets) + logger.info(f"loaded {len(self.fnames)} samples") + + def __getitem__(self, index): + import soundfile as sf + + fname = self.fnames_dict.string(self.fnames[index], separator="") + if self.root_dir: + fname = os.path.join(self.root_dir, fname) + + wav, curr_sample_rate = sf.read(fname) + feats = torch.from_numpy(wav).float() + feats = self.postprocess(feats, curr_sample_rate) + return {"id": index, "source": feats} diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_speech_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_speech_dataset.py new file mode 100644 index 00000000..c768dcfb --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_speech_dataset.py @@ -0,0 +1,428 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from dataclasses import dataclass +from pathlib import Path +from typing import Dict, List, Optional, Tuple + +import torch + +from fairseq.data import ConcatDataset, Dictionary +from fairseq.data import data_utils as fairseq_data_utils +from fairseq.data.audio.data_cfg import S2SDataConfig +from fairseq.data.audio.speech_to_text_dataset import ( + SpeechToTextDataset, + SpeechToTextDatasetCreator, + _collate_frames, + get_features_or_waveform, +) + +logger = logging.getLogger(__name__) + + +@dataclass +class SpeechToSpeechDatasetItem(object): + index: int + source: torch.Tensor + target: Optional[torch.Tensor] = None + target_speaker: Optional[torch.Tensor] = None + tgt_lang_tag: Optional[int] = None + + +class SpeechToSpeechDataset(SpeechToTextDataset): + def __init__( + self, + split: str, + is_train_split: bool, + data_cfg: S2SDataConfig, + src_audio_paths: List[str], + src_n_frames: List[int], + tgt_audio_paths: List[str], + tgt_n_frames: List[int], + src_langs: Optional[List[str]] = None, + tgt_langs: Optional[List[str]] = None, + ids: Optional[List[str]] = None, + target_is_code: bool = False, + tgt_dict: Dictionary = None, + n_frames_per_step: int = 1, + ): + tgt_texts = tgt_audio_paths if target_is_code else None + super().__init__( + split, + is_train_split, + data_cfg, + src_audio_paths, + src_n_frames, + ids=ids, + tgt_dict=tgt_dict, + tgt_texts=tgt_texts, + src_langs=src_langs, + tgt_langs=tgt_langs, + n_frames_per_step=n_frames_per_step, + ) + + self.tgt_audio_paths = tgt_audio_paths + self.tgt_lens = [t // self.n_frames_per_step for t in tgt_n_frames] + + assert not target_is_code or tgt_dict is not None + self.target_is_code = target_is_code + + assert len(tgt_audio_paths) == self.n_samples + assert len(tgt_n_frames) == self.n_samples + + self.tgt_speakers = None + if self.cfg.target_speaker_embed: + samples = SpeechToTextDatasetCreator._load_samples_from_tsv( + self.cfg.target_speaker_embed, split + ) + spk_emb_dict = {s["id"]: s["speaker_embed"] for s in samples} + self.tgt_speakers = [spk_emb_dict[id] for id in self.ids] + assert len(self.tgt_speakers) == self.n_samples + + logger.info(self.__repr__()) + + def pack_units(self, input: torch.Tensor) -> torch.Tensor: + if self.n_frames_per_step <= 1: + return input + + offset = 4 + vocab_size = ( + len(self.tgt_dict) - offset + ) # remove offset from , , , , which is specific to fairseq dictionary + + assert input.dim() == 1 + stacked_input = ( + input[:-1].view(-1, self.n_frames_per_step) - offset + ) # remove + scale = [ + pow(vocab_size, self.n_frames_per_step - 1 - i) + for i in range(self.n_frames_per_step) + ] + scale = torch.LongTensor(scale).squeeze(0) + res = input.new((len(input) - 1) // self.n_frames_per_step + 1).fill_(input[-1]) + res[:-1] = (stacked_input * scale).sum(dim=1) + offset + + return res + + def __getitem__(self, index: int) -> SpeechToSpeechDatasetItem: + source = self._get_source_audio(index) + + tgt_lang_tag = None + if self.cfg.prepend_tgt_lang_tag_as_bos: + # prepend_tgt_lang_tag_as_bos: put tgt_lang_tag as bos of target + tgt_lang_tag = self.get_lang_tag_idx(self.tgt_langs[index], self.tgt_dict) + + if not self.target_is_code: + target = get_features_or_waveform(self.tgt_audio_paths[index]) + target = torch.from_numpy(target).float() + target = self.pack_frames(target) + else: + target = self.tgt_dict.encode_line( + self.tgt_audio_paths[index], + add_if_not_exist=False, + append_eos=True, + ).long() + if self.n_frames_per_step > 1: + n_tgt_frame = target.size(0) - 1 # exclude + keep_n_tgt_frame = n_tgt_frame - n_tgt_frame % self.n_frames_per_step + target = torch.cat( + ( + target[:keep_n_tgt_frame], + target.new_full((1,), self.tgt_dict.eos()), + ), + dim=0, + ) + + if self.tgt_speakers: + tgt_spk = get_features_or_waveform(self.tgt_speakers[index]) + tgt_spk = torch.from_numpy(tgt_spk).float() + else: + tgt_spk = torch.FloatTensor([]) + + return SpeechToSpeechDatasetItem( + index=index, + source=source, + target=target, + target_speaker=tgt_spk, + tgt_lang_tag=tgt_lang_tag, + ) + + def _collate_target(self, samples: List[SpeechToSpeechDatasetItem]) -> torch.Tensor: + if self.target_is_code: + target = fairseq_data_utils.collate_tokens( + [x.target for x in samples], + self.tgt_dict.pad(), + self.tgt_dict.eos(), + left_pad=False, + move_eos_to_beginning=False, + ) + # convert stacked units to a single id + pack_targets = [self.pack_units(x.target) for x in samples] + prev_output_tokens = fairseq_data_utils.collate_tokens( + pack_targets, + self.tgt_dict.pad(), + self.tgt_dict.eos(), + left_pad=False, + move_eos_to_beginning=True, + ) + target_lengths = torch.tensor( + [x.size(0) for x in pack_targets], dtype=torch.long + ) + else: + target = _collate_frames([x.target for x in samples], is_audio_input=False) + bsz, _, d = target.size() + prev_output_tokens = torch.cat( + (target.new_full((bsz, 1, d), 0.0), target[:, :-1, :]), dim=1 + ) + target_lengths = torch.tensor( + [x.target.size(0) for x in samples], dtype=torch.long + ) + + return target, prev_output_tokens, target_lengths + + def collater( + self, samples: List[SpeechToSpeechDatasetItem], return_order: bool = False + ) -> Dict: + if len(samples) == 0: + return {} + indices = torch.tensor([x.index for x in samples], dtype=torch.long) + frames = _collate_frames([x.source for x in samples], self.cfg.use_audio_input) + # sort samples by descending number of frames + n_frames = torch.tensor([x.source.size(0) for x in samples], dtype=torch.long) + n_frames, order = n_frames.sort(descending=True) + indices = indices.index_select(0, order) + frames = frames.index_select(0, order) + + target, prev_output_tokens, target_lengths = self._collate_target(samples) + target = target.index_select(0, order) + target_lengths = target_lengths.index_select(0, order) + prev_output_tokens = prev_output_tokens.index_select(0, order) + ntokens = sum(x.target.size(0) for x in samples) + + tgt_speakers = None + if self.cfg.target_speaker_embed: + tgt_speakers = _collate_frames( + [x.target_speaker for x in samples], is_audio_input=True + ).index_select(0, order) + + net_input = { + "src_tokens": frames, + "src_lengths": n_frames, + "prev_output_tokens": prev_output_tokens, + "tgt_speaker": tgt_speakers, # TODO: unify "speaker" and "tgt_speaker" + } + if self.tgt_texts is not None and samples[0].tgt_lang_tag is not None: + for i in range(len(samples)): + net_input["prev_output_tokens"][i][0] = samples[order[i]].tgt_lang_tag + out = { + "id": indices, + "net_input": net_input, + "speaker": tgt_speakers, # to support Tacotron2 loss for speech-to-spectrogram model + "target": target, + "target_lengths": target_lengths, + "ntokens": ntokens, + "nsentences": len(samples), + } + if return_order: + out["order"] = order + return out + + +class TextTargetMultitaskData(object): + # mandatory columns + KEY_ID, KEY_TEXT = "id", "tgt_text" + + def __init__(self, args, split, tgt_dict): + samples = SpeechToTextDatasetCreator._load_samples_from_tsv(args.data, split) + self.data = {s[self.KEY_ID]: s[self.KEY_TEXT] for s in samples} + self.dict = tgt_dict + self.append_eos = args.decoder_type != "ctc" + + def get(self, sample_id): + if sample_id in self.data: + return self.dict.encode_line( + self.data[sample_id], + add_if_not_exist=False, + append_eos=self.append_eos, + ) + else: + logger.warning(f"no target for {sample_id}") + return torch.IntTensor([]) + + def collater(self, samples: List[torch.Tensor]) -> torch.Tensor: + out = fairseq_data_utils.collate_tokens( + samples, + self.dict.pad(), + self.dict.eos(), + left_pad=False, + move_eos_to_beginning=False, + ).long() + + prev_out = fairseq_data_utils.collate_tokens( + samples, + self.dict.pad(), + self.dict.eos(), + left_pad=False, + move_eos_to_beginning=True, + ).long() + + target_lengths = torch.tensor([t.size(0) for t in samples], dtype=torch.long) + ntokens = sum(t.size(0) for t in samples) + + output = { + "prev_output_tokens": prev_out, + "target": out, + "target_lengths": target_lengths, + "ntokens": ntokens, + } + + return output + + +class SpeechToSpeechMultitaskDataset(SpeechToSpeechDataset): + def __init__(self, *argv): + super().__init__(*argv) + self.multitask_data = {} + + def add_multitask_dataset(self, task_name, task_data): + self.multitask_data[task_name] = task_data + + def __getitem__( + self, index: int + ) -> Tuple[SpeechToSpeechDatasetItem, Dict[str, torch.Tensor]]: + s2s_data = super().__getitem__(index) + + multitask_target = {} + sample_id = self.ids[index] + for task_name, task_dataset in self.multitask_data.items(): + multitask_target[task_name] = task_dataset.get(sample_id) + + return s2s_data, multitask_target + + def collater( + self, samples: List[Tuple[SpeechToSpeechDatasetItem, Dict[str, torch.Tensor]]] + ) -> Dict: + if len(samples) == 0: + return {} + + out = super().collater([s for s, _ in samples], return_order=True) + order = out["order"] + del out["order"] + + for task_name, task_dataset in self.multitask_data.items(): + if "multitask" not in out: + out["multitask"] = {} + d = [s[task_name] for _, s in samples] + task_target = task_dataset.collater(d) + out["multitask"][task_name] = { + "target": task_target["target"].index_select(0, order), + "target_lengths": task_target["target_lengths"].index_select(0, order), + "ntokens": task_target["ntokens"], + } + out["multitask"][task_name]["net_input"] = { + "prev_output_tokens": task_target["prev_output_tokens"].index_select( + 0, order + ), + } + + return out + + +class SpeechToSpeechDatasetCreator(object): + # mandatory columns + KEY_ID, KEY_SRC_AUDIO, KEY_SRC_N_FRAMES = "id", "src_audio", "src_n_frames" + KEY_TGT_AUDIO, KEY_TGT_N_FRAMES = "tgt_audio", "tgt_n_frames" + # optional columns + KEY_SRC_LANG, KEY_TGT_LANG = "src_lang", "tgt_lang" + # default values + DEFAULT_LANG = "" + + @classmethod + def _from_list( + cls, + split_name: str, + is_train_split, + samples: List[Dict], + data_cfg: S2SDataConfig, + target_is_code: bool = False, + target_dictionary: Dictionary = None, + n_frames_per_step: int = 1, + multitask: Optional[Dict] = None, + ) -> SpeechToSpeechDataset: + audio_root = Path(data_cfg.audio_root) + ids = [s[cls.KEY_ID] for s in samples] + src_audio_paths = [ + (audio_root / s[cls.KEY_SRC_AUDIO]).as_posix() for s in samples + ] + tgt_audio_paths = [ + s[cls.KEY_TGT_AUDIO] + if target_is_code + else (audio_root / s[cls.KEY_TGT_AUDIO]).as_posix() + for s in samples + ] + src_n_frames = [int(s[cls.KEY_SRC_N_FRAMES]) for s in samples] + tgt_n_frames = [int(s[cls.KEY_TGT_N_FRAMES]) for s in samples] + src_langs = [s.get(cls.KEY_SRC_LANG, cls.DEFAULT_LANG) for s in samples] + tgt_langs = [s.get(cls.KEY_TGT_LANG, cls.DEFAULT_LANG) for s in samples] + + has_multitask = len(multitask) > 0 + dataset_cls = ( + SpeechToSpeechMultitaskDataset if has_multitask else SpeechToSpeechDataset + ) + + ds = dataset_cls( + split_name, + is_train_split, + data_cfg, + src_audio_paths, + src_n_frames, + tgt_audio_paths, + tgt_n_frames, + src_langs, + tgt_langs, + ids, + target_is_code, + target_dictionary, + n_frames_per_step, + ) + + if has_multitask: + for task_name, task_obj in multitask.items(): + task_data = TextTargetMultitaskData( + task_obj.args, split_name, task_obj.target_dictionary + ) + ds.add_multitask_dataset(task_name, task_data) + return ds + + @classmethod + def from_tsv( + cls, + root: str, + data_cfg: S2SDataConfig, + splits: str, + is_train_split: bool, + epoch: int, + seed: int, + target_is_code: bool = False, + target_dictionary: Dictionary = None, + n_frames_per_step: int = 1, + multitask: Optional[Dict] = None, + ) -> SpeechToSpeechDataset: + datasets = [] + for split in splits.split(","): + samples = SpeechToTextDatasetCreator._load_samples_from_tsv(root, split) + ds = cls._from_list( + split, + is_train_split, + samples, + data_cfg, + target_is_code, + target_dictionary, + n_frames_per_step, + multitask, + ) + datasets.append(ds) + return ConcatDataset(datasets) if len(datasets) > 1 else datasets[0] diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_text_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_text_dataset.py new file mode 100644 index 00000000..bfd50039 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_text_dataset.py @@ -0,0 +1,561 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import csv +import io +import logging +import re +from collections import defaultdict +from dataclasses import dataclass +from pathlib import Path +from typing import Dict, List, Optional + +import numpy as np +import torch +import torch.nn.functional as F + +from fairseq.data import ConcatDataset, Dictionary, FairseqDataset, ResamplingDataset +from fairseq.data import data_utils as fairseq_data_utils +from fairseq.data.audio.audio_utils import ( + FEATURE_OR_SF_AUDIO_FILE_EXTENSIONS, + get_fbank, + get_waveform, + is_npy_data, + is_sf_audio_data, + parse_path, + read_from_stored_zip, +) +from fairseq.data.audio.data_cfg import S2TDataConfig +from fairseq.data.audio.feature_transforms import CompositeAudioFeatureTransform + +logger = logging.getLogger(__name__) + + +def get_features_from_npy_or_audio(path): + ext = Path(path).suffix + if ext not in FEATURE_OR_SF_AUDIO_FILE_EXTENSIONS: + raise ValueError(f'Unsupported file format for "{path}"') + return np.load(path) if ext == ".npy" else get_fbank(path) + + +def get_features_or_waveform_from_stored_zip( + path, + byte_offset, + byte_size, + need_waveform=False, + use_sample_rate=None, +): + assert path.endswith(".zip") + data = read_from_stored_zip(path, byte_offset, byte_size) + f = io.BytesIO(data) + if is_npy_data(data): + features_or_waveform = np.load(f) + elif is_sf_audio_data(data): + features_or_waveform = ( + get_waveform(f, always_2d=False, output_sample_rate=use_sample_rate)[0] + if need_waveform + else get_fbank(f) + ) + else: + raise ValueError(f'Unknown file format for "{path}"') + return features_or_waveform + + +def get_features_or_waveform(path: str, need_waveform=False, use_sample_rate=None): + """Get speech features from .npy file or waveform from .wav/.flac file. + The file may be inside an uncompressed ZIP file and is accessed via byte + offset and length. + + Args: + path (str): File path in the format of "<.npy/.wav/.flac path>" or + "::". + need_waveform (bool): return waveform instead of features. + use_sample_rate (int): change sample rate for the input wave file + + Returns: + features_or_waveform (numpy.ndarray): speech features or waveform. + """ + _path, slice_ptr = parse_path(path) + if len(slice_ptr) == 0: + if need_waveform: + return get_waveform( + _path, always_2d=False, output_sample_rate=use_sample_rate + )[0] + return get_features_from_npy_or_audio(_path) + elif len(slice_ptr) == 2: + features_or_waveform = get_features_or_waveform_from_stored_zip( + _path, + slice_ptr[0], + slice_ptr[1], + need_waveform=need_waveform, + use_sample_rate=use_sample_rate, + ) + else: + raise ValueError(f"Invalid path: {path}") + + return features_or_waveform + + +def _collate_frames( + frames: List[torch.Tensor], is_audio_input: bool = False +) -> torch.Tensor: + """ + Convert a list of 2D frames into a padded 3D tensor + Args: + frames (list): list of 2D frames of size L[i]*f_dim. Where L[i] is + length of i-th frame and f_dim is static dimension of features + Returns: + 3D tensor of size len(frames)*len_max*f_dim where len_max is max of L[i] + """ + max_len = max(frame.size(0) for frame in frames) + if is_audio_input: + out = frames[0].new_zeros((len(frames), max_len)) + else: + out = frames[0].new_zeros((len(frames), max_len, frames[0].size(1))) + for i, v in enumerate(frames): + out[i, : v.size(0)] = v + return out + + +@dataclass +class SpeechToTextDatasetItem(object): + index: int + source: torch.Tensor + target: Optional[torch.Tensor] = None + speaker_id: Optional[int] = None + + +class SpeechToTextDataset(FairseqDataset): + LANG_TAG_TEMPLATE = "" + + def __init__( + self, + split: str, + is_train_split: bool, + cfg: S2TDataConfig, + audio_paths: List[str], + n_frames: List[int], + src_texts: Optional[List[str]] = None, + tgt_texts: Optional[List[str]] = None, + speakers: Optional[List[str]] = None, + src_langs: Optional[List[str]] = None, + tgt_langs: Optional[List[str]] = None, + ids: Optional[List[str]] = None, + tgt_dict: Optional[Dictionary] = None, + pre_tokenizer=None, + bpe_tokenizer=None, + n_frames_per_step=1, + speaker_to_id=None, + append_eos=True, + ): + self.split, self.is_train_split = split, is_train_split + self.cfg = cfg + self.audio_paths, self.n_frames = audio_paths, n_frames + self.n_samples = len(audio_paths) + assert len(n_frames) == self.n_samples > 0 + assert src_texts is None or len(src_texts) == self.n_samples + assert tgt_texts is None or len(tgt_texts) == self.n_samples + assert speakers is None or len(speakers) == self.n_samples + assert src_langs is None or len(src_langs) == self.n_samples + assert tgt_langs is None or len(tgt_langs) == self.n_samples + assert ids is None or len(ids) == self.n_samples + assert (tgt_dict is None and tgt_texts is None) or ( + tgt_dict is not None and tgt_texts is not None + ) + self.src_texts, self.tgt_texts = src_texts, tgt_texts + self.src_langs, self.tgt_langs = src_langs, tgt_langs + self.speakers = speakers + self.tgt_dict = tgt_dict + self.check_tgt_lang_tag() + self.ids = ids + self.shuffle = cfg.shuffle if is_train_split else False + + self.feature_transforms = CompositeAudioFeatureTransform.from_config_dict( + self.cfg.get_feature_transforms(split, is_train_split) + ) + + self.pre_tokenizer = pre_tokenizer + self.bpe_tokenizer = bpe_tokenizer + self.n_frames_per_step = n_frames_per_step + self.speaker_to_id = speaker_to_id + + self.tgt_lens = self.get_tgt_lens_and_check_oov() + self.append_eos = append_eos + + logger.info(self.__repr__()) + + def get_tgt_lens_and_check_oov(self): + if self.tgt_texts is None: + return [0 for _ in range(self.n_samples)] + tgt_lens = [] + n_tokens, n_oov_tokens = 0, 0 + for i in range(self.n_samples): + tokenized = self.get_tokenized_tgt_text(i).split(" ") + oov_tokens = [ + t + for t in tokenized + if self.tgt_dict.index(t) == self.tgt_dict.unk_index + ] + n_tokens += len(tokenized) + n_oov_tokens += len(oov_tokens) + tgt_lens.append(len(tokenized)) + logger.info(f"'{self.split}' has {n_oov_tokens / n_tokens * 100:.2f}% OOV") + return tgt_lens + + def __repr__(self): + return ( + self.__class__.__name__ + + f'(split="{self.split}", n_samples={self.n_samples:_}, ' + f"prepend_tgt_lang_tag={self.cfg.prepend_tgt_lang_tag}, " + f"shuffle={self.shuffle}, transforms={self.feature_transforms}, " + f"n_frames_per_step={self.n_frames_per_step}" + ) + + @classmethod + def is_lang_tag(cls, token): + pattern = cls.LANG_TAG_TEMPLATE.replace("{}", "(.*)") + return re.match(pattern, token) + + def check_tgt_lang_tag(self): + if self.cfg.prepend_tgt_lang_tag: + assert self.tgt_langs is not None and self.tgt_dict is not None + tgt_lang_tags = [ + self.LANG_TAG_TEMPLATE.format(t) for t in set(self.tgt_langs) + ] + assert all(t in self.tgt_dict for t in tgt_lang_tags) + + @classmethod + def tokenize(cls, tokenizer, text: str): + return text if tokenizer is None else tokenizer.encode(text) + + def get_tokenized_tgt_text(self, index: int): + text = self.tokenize(self.pre_tokenizer, self.tgt_texts[index]) + text = self.tokenize(self.bpe_tokenizer, text) + return text + + def pack_frames(self, feature: torch.Tensor): + if self.n_frames_per_step == 1: + return feature + n_packed_frames = feature.shape[0] // self.n_frames_per_step + feature = feature[: self.n_frames_per_step * n_packed_frames] + return feature.reshape(n_packed_frames, -1) + + @classmethod + def get_lang_tag_idx(cls, lang: str, dictionary: Dictionary): + lang_tag_idx = dictionary.index(cls.LANG_TAG_TEMPLATE.format(lang)) + assert lang_tag_idx != dictionary.unk() + return lang_tag_idx + + def _get_source_audio(self, index: int) -> torch.Tensor: + source = get_features_or_waveform( + self.audio_paths[index], + need_waveform=self.cfg.use_audio_input, + use_sample_rate=self.cfg.use_sample_rate, + ) + if self.cfg.use_audio_input: + source = torch.from_numpy(source).float() + if self.cfg.standardize_audio: + with torch.no_grad(): + source = F.layer_norm(source, source.shape) + else: + if self.feature_transforms is not None: + source = self.feature_transforms(source) + source = torch.from_numpy(source).float() + return source + + def __getitem__(self, index: int) -> SpeechToTextDatasetItem: + source = self._get_source_audio(index) + source = self.pack_frames(source) + + target = None + if self.tgt_texts is not None: + tokenized = self.get_tokenized_tgt_text(index) + target = self.tgt_dict.encode_line( + tokenized, add_if_not_exist=False, append_eos=self.append_eos + ).long() + if self.cfg.prepend_tgt_lang_tag: + lang_tag_idx = self.get_lang_tag_idx( + self.tgt_langs[index], self.tgt_dict + ) + target = torch.cat((torch.LongTensor([lang_tag_idx]), target), 0) + + if self.cfg.prepend_bos_and_append_tgt_lang_tag: + bos = torch.LongTensor([self.tgt_dict.bos()]) + lang_tag_idx = self.get_lang_tag_idx(self.tgt_langs[index], self.tgt_dict) + assert lang_tag_idx != self.tgt_dict.unk() + lang_tag_idx = torch.LongTensor([lang_tag_idx]) + target = torch.cat((bos, target, lang_tag_idx), 0) + + speaker_id = None + if self.speaker_to_id is not None: + speaker_id = self.speaker_to_id[self.speakers[index]] + return SpeechToTextDatasetItem( + index=index, source=source, target=target, speaker_id=speaker_id + ) + + def __len__(self): + return self.n_samples + + def collater( + self, samples: List[SpeechToTextDatasetItem], return_order: bool = False + ) -> Dict: + if len(samples) == 0: + return {} + indices = torch.tensor([x.index for x in samples], dtype=torch.long) + frames = _collate_frames([x.source for x in samples], self.cfg.use_audio_input) + # sort samples by descending number of frames + n_frames = torch.tensor([x.source.size(0) for x in samples], dtype=torch.long) + n_frames, order = n_frames.sort(descending=True) + indices = indices.index_select(0, order) + frames = frames.index_select(0, order) + + target, target_lengths = None, None + prev_output_tokens = None + ntokens = None + if self.tgt_texts is not None: + target = fairseq_data_utils.collate_tokens( + [x.target for x in samples], + self.tgt_dict.pad(), + self.tgt_dict.eos(), + left_pad=False, + move_eos_to_beginning=False, + ) + target = target.index_select(0, order) + target_lengths = torch.tensor( + [x.target.size(0) for x in samples], dtype=torch.long + ).index_select(0, order) + prev_output_tokens = fairseq_data_utils.collate_tokens( + [x.target for x in samples], + self.tgt_dict.pad(), + eos_idx=None, + left_pad=False, + move_eos_to_beginning=True, + ) + prev_output_tokens = prev_output_tokens.index_select(0, order) + ntokens = sum(x.target.size(0) for x in samples) + + speaker = None + if self.speaker_to_id is not None: + speaker = ( + torch.tensor([s.speaker_id for s in samples], dtype=torch.long) + .index_select(0, order) + .view(-1, 1) + ) + + net_input = { + "src_tokens": frames, + "src_lengths": n_frames, + "prev_output_tokens": prev_output_tokens, + } + out = { + "id": indices, + "net_input": net_input, + "speaker": speaker, + "target": target, + "target_lengths": target_lengths, + "ntokens": ntokens, + "nsentences": len(samples), + } + if return_order: + out["order"] = order + return out + + def num_tokens(self, index): + return self.n_frames[index] + + def size(self, index): + return self.n_frames[index], self.tgt_lens[index] + + @property + def sizes(self): + return np.array(self.n_frames) + + @property + def can_reuse_epoch_itr_across_epochs(self): + return True + + def ordered_indices(self): + if self.shuffle: + order = [np.random.permutation(len(self))] + else: + order = [np.arange(len(self))] + # first by descending order of # of frames then by original/random order + order.append([-n for n in self.n_frames]) + return np.lexsort(order) + + def prefetch(self, indices): + raise False + + +class SpeechToTextDatasetCreator(object): + # mandatory columns + KEY_ID, KEY_AUDIO, KEY_N_FRAMES = "id", "audio", "n_frames" + KEY_TGT_TEXT = "tgt_text" + # optional columns + KEY_SPEAKER, KEY_SRC_TEXT = "speaker", "src_text" + KEY_SRC_LANG, KEY_TGT_LANG = "src_lang", "tgt_lang" + # default values + DEFAULT_SPEAKER = DEFAULT_SRC_TEXT = DEFAULT_LANG = "" + + @classmethod + def _from_list( + cls, + split_name: str, + is_train_split, + samples: List[Dict], + cfg: S2TDataConfig, + tgt_dict, + pre_tokenizer, + bpe_tokenizer, + n_frames_per_step, + speaker_to_id, + ) -> SpeechToTextDataset: + audio_root = Path(cfg.audio_root) + ids = [s[cls.KEY_ID] for s in samples] + audio_paths = [(audio_root / s[cls.KEY_AUDIO]).as_posix() for s in samples] + n_frames = [int(s[cls.KEY_N_FRAMES]) for s in samples] + tgt_texts = [s[cls.KEY_TGT_TEXT] for s in samples] + src_texts = [s.get(cls.KEY_SRC_TEXT, cls.DEFAULT_SRC_TEXT) for s in samples] + speakers = [s.get(cls.KEY_SPEAKER, cls.DEFAULT_SPEAKER) for s in samples] + src_langs = [s.get(cls.KEY_SRC_LANG, cls.DEFAULT_LANG) for s in samples] + tgt_langs = [s.get(cls.KEY_TGT_LANG, cls.DEFAULT_LANG) for s in samples] + return SpeechToTextDataset( + split_name, + is_train_split, + cfg, + audio_paths, + n_frames, + src_texts=src_texts, + tgt_texts=tgt_texts, + speakers=speakers, + src_langs=src_langs, + tgt_langs=tgt_langs, + ids=ids, + tgt_dict=tgt_dict, + pre_tokenizer=pre_tokenizer, + bpe_tokenizer=bpe_tokenizer, + n_frames_per_step=n_frames_per_step, + speaker_to_id=speaker_to_id, + ) + + @classmethod + def get_size_ratios( + cls, datasets: List[SpeechToTextDataset], alpha: float = 1.0 + ) -> List[float]: + """Size ratios for temperature-based sampling + (https://arxiv.org/abs/1907.05019)""" + + id_to_lp, lp_to_sz = {}, defaultdict(int) + for ds in datasets: + lang_pairs = {f"{s}->{t}" for s, t in zip(ds.src_langs, ds.tgt_langs)} + assert len(lang_pairs) == 1 + lang_pair = list(lang_pairs)[0] + id_to_lp[ds.split] = lang_pair + lp_to_sz[lang_pair] += sum(ds.n_frames) + + sz_sum = sum(v for v in lp_to_sz.values()) + lp_to_prob = {k: v / sz_sum for k, v in lp_to_sz.items()} + lp_to_tgt_prob = {k: v**alpha for k, v in lp_to_prob.items()} + prob_sum = sum(v for v in lp_to_tgt_prob.values()) + lp_to_tgt_prob = {k: v / prob_sum for k, v in lp_to_tgt_prob.items()} + lp_to_sz_ratio = { + k: (lp_to_tgt_prob[k] * sz_sum) / v for k, v in lp_to_sz.items() + } + size_ratio = [lp_to_sz_ratio[id_to_lp[ds.split]] for ds in datasets] + + p_formatted = { + k: f"{lp_to_prob[k]:.3f}->{lp_to_tgt_prob[k]:.3f}" for k in lp_to_sz + } + logger.info(f"sampling probability balancing: {p_formatted}") + sr_formatted = {ds.split: f"{r:.3f}" for ds, r in zip(datasets, size_ratio)} + logger.info(f"balanced sampling size ratio: {sr_formatted}") + return size_ratio + + @classmethod + def _load_samples_from_tsv(cls, root: str, split: str): + tsv_path = Path(root) / f"{split}.tsv" + if not tsv_path.is_file(): + raise FileNotFoundError(f"Dataset not found: {tsv_path}") + with open(tsv_path) as f: + reader = csv.DictReader( + f, + delimiter="\t", + quotechar=None, + doublequote=False, + lineterminator="\n", + quoting=csv.QUOTE_NONE, + ) + samples = [dict(e) for e in reader] + if len(samples) == 0: + raise ValueError(f"Empty manifest: {tsv_path}") + return samples + + @classmethod + def _from_tsv( + cls, + root: str, + cfg: S2TDataConfig, + split: str, + tgt_dict, + is_train_split: bool, + pre_tokenizer, + bpe_tokenizer, + n_frames_per_step, + speaker_to_id, + ) -> SpeechToTextDataset: + samples = cls._load_samples_from_tsv(root, split) + return cls._from_list( + split, + is_train_split, + samples, + cfg, + tgt_dict, + pre_tokenizer, + bpe_tokenizer, + n_frames_per_step, + speaker_to_id, + ) + + @classmethod + def from_tsv( + cls, + root: str, + cfg: S2TDataConfig, + splits: str, + tgt_dict, + pre_tokenizer, + bpe_tokenizer, + is_train_split: bool, + epoch: int, + seed: int, + n_frames_per_step: int = 1, + speaker_to_id=None, + ) -> SpeechToTextDataset: + datasets = [ + cls._from_tsv( + root, + cfg, + split, + tgt_dict, + is_train_split, + pre_tokenizer, + bpe_tokenizer, + n_frames_per_step, + speaker_to_id, + ) + for split in splits.split(",") + ] + + if is_train_split and len(datasets) > 1 and cfg.sampling_alpha != 1.0: + # temperature-based sampling + size_ratios = cls.get_size_ratios(datasets, alpha=cfg.sampling_alpha) + datasets = [ + ResamplingDataset( + d, size_ratio=r, seed=seed, epoch=epoch, replace=(r >= 1.0) + ) + for r, d in zip(size_ratios, datasets) + ] + + return ConcatDataset(datasets) if len(datasets) > 1 else datasets[0] diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_text_joint_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_text_joint_dataset.py new file mode 100644 index 00000000..06922ea0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/speech_to_text_joint_dataset.py @@ -0,0 +1,359 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from pathlib import Path +from typing import Dict, List, NamedTuple, Optional + +import torch + +from fairseq.data import ConcatDataset, Dictionary, ResamplingDataset +from fairseq.data import data_utils as fairseq_data_utils +from fairseq.data.audio.speech_to_text_dataset import ( + S2TDataConfig, + SpeechToTextDataset, + SpeechToTextDatasetCreator, +) + +logger = logging.getLogger(__name__) + + +class S2TJointDataConfig(S2TDataConfig): + """Wrapper class for data config YAML""" + + @property + def src_vocab_filename(self): + """fairseq vocabulary file under data root""" + return self.config.get("src_vocab_filename", "src_dict.txt") + + @property + def src_pre_tokenizer(self) -> Dict: + """Pre-tokenizer to apply before subword tokenization. Returning + a dictionary with `tokenizer` providing the tokenizer name and + the other items providing the tokenizer-specific arguments. + Tokenizers are defined in `fairseq.data.encoders.*`""" + return self.config.get("src_pre_tokenizer", {"tokenizer": None}) + + @property + def src_bpe_tokenizer(self) -> Dict: + """Subword tokenizer to apply on source text after pre-tokenization. + Returning a dictionary with `bpe` providing the tokenizer name and + the other items providing the tokenizer-specific arguments. + Tokenizers are defined in `fairseq.data.encoders.*`""" + return self.config.get("src_bpe_tokenizer", {"bpe": None}) + + @property + def prepend_tgt_lang_tag_no_change(self) -> bool: + """Prepend target lang ID token as the prev_output_tokens BOS (e.g. for + to-many multilingual setting). No change needed during inference. + This option is deprecated and replaced by prepend_tgt_lang_tag_as_bos. + """ + value = self.config.get("prepend_tgt_lang_tag_no_change", None) + if value is None: + return self.config.get("prepend_tgt_lang_tag_as_bos", False) + return value + + @property + def sampling_text_alpha(self): + """Hyper-parameter alpha = 1/T for temperature-based resampling. (text + input only) (alpha = 1 for no resampling)""" + return self.config.get("sampling_text_alpha", 1.0) + + +class SpeechToTextJointDatasetItem(NamedTuple): + index: int + source: torch.Tensor + target: Optional[torch.Tensor] = None + src_txt_tokens: Optional[torch.Tensor] = None + tgt_lang_tag: Optional[int] = None + src_lang_tag: Optional[int] = None + tgt_alignment: Optional[torch.Tensor] = None + + +# use_src_lang_id: +# 0: don't use src_lang_id +# 1: attach src_lang_id to the src_txt_tokens as eos +class SpeechToTextJointDataset(SpeechToTextDataset): + def __init__( + self, + split: str, + is_train_split: bool, + cfg: S2TJointDataConfig, + audio_paths: List[str], + n_frames: List[int], + src_texts: Optional[List[str]] = None, + tgt_texts: Optional[List[str]] = None, + speakers: Optional[List[str]] = None, + src_langs: Optional[List[str]] = None, + tgt_langs: Optional[List[str]] = None, + ids: Optional[List[str]] = None, + tgt_dict: Optional[Dictionary] = None, + src_dict: Optional[Dictionary] = None, + pre_tokenizer=None, + bpe_tokenizer=None, + src_pre_tokenizer=None, + src_bpe_tokenizer=None, + append_eos: Optional[bool] = True, + alignment: Optional[List[str]] = None, + use_src_lang_id: Optional[int] = 0, + ): + super().__init__( + split, + is_train_split, + cfg, + audio_paths, + n_frames, + src_texts=src_texts, + tgt_texts=tgt_texts, + speakers=speakers, + src_langs=src_langs, + tgt_langs=tgt_langs, + ids=ids, + tgt_dict=tgt_dict, + pre_tokenizer=pre_tokenizer, + bpe_tokenizer=bpe_tokenizer, + append_eos=append_eos, + ) + + self.src_dict = src_dict + self.src_pre_tokenizer = src_pre_tokenizer + self.src_bpe_tokenizer = src_bpe_tokenizer + self.alignment = None + self.use_src_lang_id = use_src_lang_id + if alignment is not None: + self.alignment = [ + [float(s) for s in sample.split()] for sample in alignment + ] + + def get_tokenized_src_text(self, index: int): + text = self.tokenize(self.src_pre_tokenizer, self.src_texts[index]) + text = self.tokenize(self.src_bpe_tokenizer, text) + return text + + def __getitem__(self, index: int) -> SpeechToTextJointDatasetItem: + s2t_dataset_item = super().__getitem__(index) + src_tokens = None + src_lang_tag = None + if self.src_texts is not None and self.src_dict is not None: + src_tokens = self.get_tokenized_src_text(index) + src_tokens = self.src_dict.encode_line( + src_tokens, add_if_not_exist=False, append_eos=True + ).long() + if self.use_src_lang_id > 0: + src_lang_tag = self.get_lang_tag_idx( + self.src_langs[index], self.src_dict + ) + tgt_lang_tag = None + if self.cfg.prepend_tgt_lang_tag_no_change: + # prepend_tgt_lang_tag_no_change: modify prev_output_tokens instead + tgt_lang_tag = self.get_lang_tag_idx(self.tgt_langs[index], self.tgt_dict) + ali = None + if self.alignment is not None: + ali = torch.Tensor(self.alignment[index]).float() + + return SpeechToTextJointDatasetItem( + index=index, + source=s2t_dataset_item.source, + target=s2t_dataset_item.target, + src_txt_tokens=src_tokens, + tgt_lang_tag=tgt_lang_tag, + src_lang_tag=src_lang_tag, + tgt_alignment=ali, + ) + + def __len__(self): + return self.n_samples + + def collater(self, samples: List[SpeechToTextJointDatasetItem]) -> Dict: + s2t_out = super().collater(samples, return_order=True) + if s2t_out == {}: + return s2t_out + net_input, order = s2t_out["net_input"], s2t_out["order"] + + if self.src_texts is not None and self.src_dict is not None: + src_txt_tokens = fairseq_data_utils.collate_tokens( + [x.src_txt_tokens for x in samples], + self.src_dict.pad(), + self.src_dict.eos(), + left_pad=False, + move_eos_to_beginning=False, + ) + src_txt_lengths = torch.tensor( + [x.src_txt_tokens.size()[0] for x in samples], dtype=torch.long + ) + if self.use_src_lang_id > 0: + src_lang_idxs = torch.tensor( + [s.src_lang_tag for s in samples], dtype=src_txt_tokens.dtype + ) + if self.use_src_lang_id == 1: # replace eos with lang_id + eos_idx = src_txt_lengths - 1 + src_txt_tokens.scatter_( + 1, eos_idx.view(-1, 1), src_lang_idxs.view(-1, 1) + ) + else: + raise NotImplementedError("Implementation is required") + + src_txt_tokens = src_txt_tokens.index_select(0, order) + src_txt_lengths = src_txt_lengths.index_select(0, order) + net_input["src_txt_tokens"] = src_txt_tokens + net_input["src_txt_lengths"] = src_txt_lengths + + net_input["alignment"] = None + if self.alignment is not None: + max_len = max([s.tgt_alignment.size(0) for s in samples]) + alignment = torch.ones(len(samples), max_len).float() + for i, s in enumerate(samples): + cur_len = s.tgt_alignment.size(0) + alignment[i][:cur_len].copy_(s.tgt_alignment) + net_input["alignment"] = alignment.index_select(0, order) + + if self.tgt_texts is not None and samples[0].tgt_lang_tag is not None: + for i in range(len(samples)): + net_input["prev_output_tokens"][i][0] = samples[order[i]].tgt_lang_tag + + out = { + "id": s2t_out["id"], + "net_input": net_input, + "target": s2t_out["target"], + "target_lengths": s2t_out["target_lengths"], + "ntokens": s2t_out["ntokens"], + "nsentences": len(samples), + } + return out + + +class SpeechToTextJointDatasetCreator(SpeechToTextDatasetCreator): + KEY_ALIGN = "align" + + @classmethod + def _from_list( + cls, + split_name: str, + is_train_split, + samples: List[Dict], + cfg: S2TJointDataConfig, + tgt_dict, + src_dict, + pre_tokenizer, + bpe_tokenizer, + src_pre_tokenizer, + src_bpe_tokenizer, + append_eos, + use_src_lang_id, + ) -> SpeechToTextJointDataset: + audio_root = Path(cfg.audio_root) + ids = [s[cls.KEY_ID] for s in samples] + audio_paths = [(audio_root / s[cls.KEY_AUDIO]).as_posix() for s in samples] + n_frames = [int(s[cls.KEY_N_FRAMES]) for s in samples] + tgt_texts = [s[cls.KEY_TGT_TEXT] for s in samples] + src_texts = [s.get(cls.KEY_SRC_TEXT, cls.DEFAULT_SRC_TEXT) for s in samples] + speakers = [s.get(cls.KEY_SPEAKER, cls.DEFAULT_SPEAKER) for s in samples] + src_langs = [s.get(cls.KEY_SRC_LANG, cls.DEFAULT_LANG) for s in samples] + tgt_langs = [s.get(cls.KEY_TGT_LANG, cls.DEFAULT_LANG) for s in samples] + tgt_alignment = None + if cls.KEY_ALIGN in samples[0].keys(): + tgt_alignment = [s[cls.KEY_ALIGN] for s in samples] + return SpeechToTextJointDataset( + split_name, + is_train_split, + cfg, + audio_paths, + n_frames, + src_texts=src_texts, + tgt_texts=tgt_texts, + speakers=speakers, + src_langs=src_langs, + tgt_langs=tgt_langs, + ids=ids, + tgt_dict=tgt_dict, + src_dict=src_dict, + pre_tokenizer=pre_tokenizer, + bpe_tokenizer=bpe_tokenizer, + src_pre_tokenizer=src_pre_tokenizer, + src_bpe_tokenizer=src_bpe_tokenizer, + append_eos=append_eos, + alignment=tgt_alignment, + use_src_lang_id=use_src_lang_id, + ) + + @classmethod + def _from_tsv( + cls, + root: str, + cfg: S2TJointDataConfig, + split: str, + tgt_dict, + src_dict, + is_train_split: bool, + pre_tokenizer, + bpe_tokenizer, + src_pre_tokenizer, + src_bpe_tokenizer, + append_eos: bool, + use_src_lang_id: int, + ) -> SpeechToTextJointDataset: + samples = cls._load_samples_from_tsv(root, split) + return cls._from_list( + split, + is_train_split, + samples, + cfg, + tgt_dict, + src_dict, + pre_tokenizer, + bpe_tokenizer, + src_pre_tokenizer, + src_bpe_tokenizer, + append_eos, + use_src_lang_id, + ) + + @classmethod + def from_tsv( + cls, + root: str, + cfg: S2TJointDataConfig, + splits: str, + tgt_dict, + src_dict, + pre_tokenizer, + bpe_tokenizer, + src_pre_tokenizer, + src_bpe_tokenizer, + is_train_split: bool, + epoch: int, + seed: int, + append_eos: Optional[bool] = True, + use_src_lang_id: Optional[int] = 0, + ) -> SpeechToTextJointDataset: + datasets = [ + cls._from_tsv( + root, + cfg, + split, + tgt_dict, + src_dict, + is_train_split, + pre_tokenizer, + bpe_tokenizer, + src_pre_tokenizer, + src_bpe_tokenizer, + append_eos=append_eos, + use_src_lang_id=use_src_lang_id, + ) + for split in splits.split(",") + ] + + if is_train_split and len(datasets) > 1 and cfg.sampling_alpha != 1.0: + # temperature-based sampling + size_ratios = cls.get_size_ratios(datasets, alpha=cfg.sampling_alpha) + datasets = [ + ResamplingDataset( + d, size_ratio=r, seed=seed, epoch=epoch, replace=(r >= 1.0) + ) + for r, d in zip(size_ratios, datasets) + ] + + return ConcatDataset(datasets) if len(datasets) > 1 else datasets[0] diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/audio/text_to_speech_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/audio/text_to_speech_dataset.py new file mode 100644 index 00000000..0e1489ae --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/audio/text_to_speech_dataset.py @@ -0,0 +1,248 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory.abs + +from pathlib import Path +from typing import List, Dict, Optional, Any +from dataclasses import dataclass + +import numpy as np +import torch + +from fairseq.data.audio.speech_to_text_dataset import ( + SpeechToTextDataset, + SpeechToTextDatasetCreator, + S2TDataConfig, + _collate_frames, + get_features_or_waveform, +) +from fairseq.data import Dictionary, data_utils as fairseq_data_utils + + +@dataclass +class TextToSpeechDatasetItem(object): + index: int + source: torch.Tensor + target: Optional[torch.Tensor] = None + speaker_id: Optional[int] = None + duration: Optional[torch.Tensor] = None + pitch: Optional[torch.Tensor] = None + energy: Optional[torch.Tensor] = None + + +class TextToSpeechDataset(SpeechToTextDataset): + def __init__( + self, + split: str, + is_train_split: bool, + cfg: S2TDataConfig, + audio_paths: List[str], + n_frames: List[int], + src_texts: Optional[List[str]] = None, + tgt_texts: Optional[List[str]] = None, + speakers: Optional[List[str]] = None, + src_langs: Optional[List[str]] = None, + tgt_langs: Optional[List[str]] = None, + ids: Optional[List[str]] = None, + tgt_dict: Optional[Dictionary] = None, + pre_tokenizer=None, + bpe_tokenizer=None, + n_frames_per_step=1, + speaker_to_id=None, + durations: Optional[List[List[int]]] = None, + pitches: Optional[List[str]] = None, + energies: Optional[List[str]] = None, + ): + super(TextToSpeechDataset, self).__init__( + split, + is_train_split, + cfg, + audio_paths, + n_frames, + src_texts=src_texts, + tgt_texts=tgt_texts, + speakers=speakers, + src_langs=src_langs, + tgt_langs=tgt_langs, + ids=ids, + tgt_dict=tgt_dict, + pre_tokenizer=pre_tokenizer, + bpe_tokenizer=bpe_tokenizer, + n_frames_per_step=n_frames_per_step, + speaker_to_id=speaker_to_id, + ) + self.durations = durations + self.pitches = pitches + self.energies = energies + + def __getitem__(self, index: int) -> TextToSpeechDatasetItem: + s2t_item = super().__getitem__(index) + + duration, pitch, energy = None, None, None + if self.durations is not None: + duration = torch.tensor( + self.durations[index] + [0], dtype=torch.long # pad 0 for EOS + ) + if self.pitches is not None: + pitch = get_features_or_waveform(self.pitches[index]) + pitch = torch.from_numpy( + np.concatenate((pitch, [0])) # pad 0 for EOS + ).float() + if self.energies is not None: + energy = get_features_or_waveform(self.energies[index]) + energy = torch.from_numpy( + np.concatenate((energy, [0])) # pad 0 for EOS + ).float() + return TextToSpeechDatasetItem( + index=index, + source=s2t_item.source, + target=s2t_item.target, + speaker_id=s2t_item.speaker_id, + duration=duration, + pitch=pitch, + energy=energy, + ) + + def collater(self, samples: List[TextToSpeechDatasetItem]) -> Dict[str, Any]: + if len(samples) == 0: + return {} + + src_lengths, order = torch.tensor( + [s.target.shape[0] for s in samples], dtype=torch.long + ).sort(descending=True) + id_ = torch.tensor([s.index for s in samples], dtype=torch.long).index_select( + 0, order + ) + feat = _collate_frames( + [s.source for s in samples], self.cfg.use_audio_input + ).index_select(0, order) + target_lengths = torch.tensor( + [s.source.shape[0] for s in samples], dtype=torch.long + ).index_select(0, order) + + src_tokens = fairseq_data_utils.collate_tokens( + [s.target for s in samples], + self.tgt_dict.pad(), + self.tgt_dict.eos(), + left_pad=False, + move_eos_to_beginning=False, + ).index_select(0, order) + + speaker = None + if self.speaker_to_id is not None: + speaker = ( + torch.tensor([s.speaker_id for s in samples], dtype=torch.long) + .index_select(0, order) + .view(-1, 1) + ) + + bsz, _, d = feat.size() + prev_output_tokens = torch.cat( + (feat.new_zeros((bsz, 1, d)), feat[:, :-1, :]), dim=1 + ) + + durations, pitches, energies = None, None, None + if self.durations is not None: + durations = fairseq_data_utils.collate_tokens( + [s.duration for s in samples], 0 + ).index_select(0, order) + assert src_tokens.shape[1] == durations.shape[1] + if self.pitches is not None: + pitches = _collate_frames([s.pitch for s in samples], True) + pitches = pitches.index_select(0, order) + assert src_tokens.shape[1] == pitches.shape[1] + if self.energies is not None: + energies = _collate_frames([s.energy for s in samples], True) + energies = energies.index_select(0, order) + assert src_tokens.shape[1] == energies.shape[1] + src_texts = [self.tgt_dict.string(samples[i].target) for i in order] + + return { + "id": id_, + "net_input": { + "src_tokens": src_tokens, + "src_lengths": src_lengths, + "prev_output_tokens": prev_output_tokens, + }, + "speaker": speaker, + "target": feat, + "durations": durations, + "pitches": pitches, + "energies": energies, + "target_lengths": target_lengths, + "ntokens": sum(target_lengths).item(), + "nsentences": len(samples), + "src_texts": src_texts, + } + + +class TextToSpeechDatasetCreator(SpeechToTextDatasetCreator): + KEY_DURATION = "duration" + KEY_PITCH = "pitch" + KEY_ENERGY = "energy" + + @classmethod + def _from_list( + cls, + split_name: str, + is_train_split, + samples: List[Dict], + cfg: S2TDataConfig, + tgt_dict, + pre_tokenizer, + bpe_tokenizer, + n_frames_per_step, + speaker_to_id, + ) -> TextToSpeechDataset: + audio_root = Path(cfg.audio_root) + ids = [s[cls.KEY_ID] for s in samples] + audio_paths = [(audio_root / s[cls.KEY_AUDIO]).as_posix() for s in samples] + n_frames = [int(s[cls.KEY_N_FRAMES]) for s in samples] + tgt_texts = [s[cls.KEY_TGT_TEXT] for s in samples] + src_texts = [s.get(cls.KEY_SRC_TEXT, cls.DEFAULT_SRC_TEXT) for s in samples] + speakers = [s.get(cls.KEY_SPEAKER, cls.DEFAULT_SPEAKER) for s in samples] + src_langs = [s.get(cls.KEY_SRC_LANG, cls.DEFAULT_LANG) for s in samples] + tgt_langs = [s.get(cls.KEY_TGT_LANG, cls.DEFAULT_LANG) for s in samples] + + durations = [s.get(cls.KEY_DURATION, None) for s in samples] + durations = [ + None if dd is None else [int(d) for d in dd.split(" ")] for dd in durations + ] + durations = None if any(dd is None for dd in durations) else durations + + pitches = [s.get(cls.KEY_PITCH, None) for s in samples] + pitches = [ + None if pp is None else (audio_root / pp).as_posix() for pp in pitches + ] + pitches = None if any(pp is None for pp in pitches) else pitches + + energies = [s.get(cls.KEY_ENERGY, None) for s in samples] + energies = [ + None if ee is None else (audio_root / ee).as_posix() for ee in energies + ] + energies = None if any(ee is None for ee in energies) else energies + + return TextToSpeechDataset( + split_name, + is_train_split, + cfg, + audio_paths, + n_frames, + src_texts, + tgt_texts, + speakers, + src_langs, + tgt_langs, + ids, + tgt_dict, + pre_tokenizer, + bpe_tokenizer, + n_frames_per_step, + speaker_to_id, + durations, + pitches, + energies, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/backtranslation_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/backtranslation_dataset.py new file mode 100644 index 00000000..8f70c90d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/backtranslation_dataset.py @@ -0,0 +1,165 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from fairseq import utils + +from . import FairseqDataset + + +def backtranslate_samples(samples, collate_fn, generate_fn, cuda=True): + """Backtranslate a list of samples. + + Given an input (*samples*) of the form: + + [{'id': 1, 'source': 'hallo welt'}] + + this will return: + + [{'id': 1, 'source': 'hello world', 'target': 'hallo welt'}] + + Args: + samples (List[dict]): samples to backtranslate. Individual samples are + expected to have a 'source' key, which will become the 'target' + after backtranslation. + collate_fn (callable): function to collate samples into a mini-batch + generate_fn (callable): function to generate backtranslations + cuda (bool): use GPU for generation (default: ``True``) + + Returns: + List[dict]: an updated list of samples with a backtranslated source + """ + collated_samples = collate_fn(samples) + s = utils.move_to_cuda(collated_samples) if cuda else collated_samples + generated_sources = generate_fn(s) + + id_to_src = {sample["id"]: sample["source"] for sample in samples} + + # Go through each tgt sentence in batch and its corresponding best + # generated hypothesis and create a backtranslation data pair + # {id: id, source: generated backtranslation, target: original tgt} + return [ + { + "id": id.item(), + "target": id_to_src[id.item()], + "source": hypos[0]["tokens"].cpu(), + } + for id, hypos in zip(collated_samples["id"], generated_sources) + ] + + +class BacktranslationDataset(FairseqDataset): + """ + Sets up a backtranslation dataset which takes a tgt batch, generates + a src using a tgt-src backtranslation function (*backtranslation_fn*), + and returns the corresponding `{generated src, input tgt}` batch. + + Args: + tgt_dataset (~fairseq.data.FairseqDataset): the dataset to be + backtranslated. Only the source side of this dataset will be used. + After backtranslation, the source sentences in this dataset will be + returned as the targets. + src_dict (~fairseq.data.Dictionary): the dictionary of backtranslated + sentences. + tgt_dict (~fairseq.data.Dictionary, optional): the dictionary of + sentences to be backtranslated. + backtranslation_fn (callable, optional): function to call to generate + backtranslations. This is typically the `generate` method of a + :class:`~fairseq.sequence_generator.SequenceGenerator` object. + Pass in None when it is not available at initialization time, and + use set_backtranslation_fn function to set it when available. + output_collater (callable, optional): function to call on the + backtranslated samples to create the final batch + (default: ``tgt_dataset.collater``). + cuda: use GPU for generation + """ + + def __init__( + self, + tgt_dataset, + src_dict, + tgt_dict=None, + backtranslation_fn=None, + output_collater=None, + cuda=True, + **kwargs + ): + self.tgt_dataset = tgt_dataset + self.backtranslation_fn = backtranslation_fn + self.output_collater = ( + output_collater if output_collater is not None else tgt_dataset.collater + ) + self.cuda = cuda if torch.cuda.is_available() else False + self.src_dict = src_dict + self.tgt_dict = tgt_dict + + def __getitem__(self, index): + """ + Returns a single sample from *tgt_dataset*. Note that backtranslation is + not applied in this step; use :func:`collater` instead to backtranslate + a batch of samples. + """ + return self.tgt_dataset[index] + + def __len__(self): + return len(self.tgt_dataset) + + def set_backtranslation_fn(self, backtranslation_fn): + self.backtranslation_fn = backtranslation_fn + + def collater(self, samples): + """Merge and backtranslate a list of samples to form a mini-batch. + + Using the samples from *tgt_dataset*, load a collated target sample to + feed to the backtranslation model. Then take the backtranslation with + the best score as the source and the original input as the target. + + Note: we expect *tgt_dataset* to provide a function `collater()` that + will collate samples into the format expected by *backtranslation_fn*. + After backtranslation, we will feed the new list of samples (i.e., the + `(backtranslated source, original source)` pairs) to *output_collater* + and return the result. + + Args: + samples (List[dict]): samples to backtranslate and collate + + Returns: + dict: a mini-batch with keys coming from *output_collater* + """ + if samples[0].get("is_dummy", False): + return samples + samples = backtranslate_samples( + samples=samples, + collate_fn=self.tgt_dataset.collater, + generate_fn=(lambda net_input: self.backtranslation_fn(net_input)), + cuda=self.cuda, + ) + return self.output_collater(samples) + + def num_tokens(self, index): + """Just use the tgt dataset num_tokens""" + return self.tgt_dataset.num_tokens(index) + + def ordered_indices(self): + """Just use the tgt dataset ordered_indices""" + return self.tgt_dataset.ordered_indices() + + def size(self, index): + """Return an example's size as a float or tuple. This value is used + when filtering a dataset with ``--max-positions``. + + Note: we use *tgt_dataset* to approximate the length of the source + sentence, since we do not know the actual length until after + backtranslation. + """ + tgt_size = self.tgt_dataset.size(index)[0] + return (tgt_size, tgt_size) + + @property + def supports_prefetch(self): + return getattr(self.tgt_dataset, "supports_prefetch", False) + + def prefetch(self, indices): + return self.tgt_dataset.prefetch(indices) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/base_wrapper_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/base_wrapper_dataset.py new file mode 100644 index 00000000..134d398b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/base_wrapper_dataset.py @@ -0,0 +1,78 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from torch.utils.data.dataloader import default_collate + +from . import FairseqDataset + + +class BaseWrapperDataset(FairseqDataset): + def __init__(self, dataset): + super().__init__() + self.dataset = dataset + + def __getitem__(self, index): + return self.dataset[index] + + def __len__(self): + return len(self.dataset) + + def collater(self, samples): + if hasattr(self.dataset, "collater"): + return self.dataset.collater(samples) + else: + return default_collate(samples) + + @property + def sizes(self): + return self.dataset.sizes + + def num_tokens(self, index): + return self.dataset.num_tokens(index) + + def size(self, index): + return self.dataset.size(index) + + def ordered_indices(self): + return self.dataset.ordered_indices() + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def attr(self, attr: str, index: int): + return self.dataset.attr(attr, index) + + def prefetch(self, indices): + self.dataset.prefetch(indices) + + def get_batch_shapes(self): + return self.dataset.get_batch_shapes() + + def batch_by_size( + self, + indices, + max_tokens=None, + max_sentences=None, + required_batch_size_multiple=1, + ): + return self.dataset.batch_by_size( + indices, + max_tokens=max_tokens, + max_sentences=max_sentences, + required_batch_size_multiple=required_batch_size_multiple, + ) + + def filter_indices_by_size(self, indices, max_sizes): + return self.dataset.filter_indices_by_size(indices, max_sizes) + + @property + def can_reuse_epoch_itr_across_epochs(self): + return self.dataset.can_reuse_epoch_itr_across_epochs + + def set_epoch(self, epoch): + super().set_epoch(epoch) + if hasattr(self.dataset, "set_epoch"): + self.dataset.set_epoch(epoch) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/bucket_pad_length_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/bucket_pad_length_dataset.py new file mode 100644 index 00000000..0f941001 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/bucket_pad_length_dataset.py @@ -0,0 +1,78 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch.nn.functional as F +from fairseq.data import BaseWrapperDataset +from fairseq.data.data_utils import get_buckets, get_bucketed_sizes + + +class BucketPadLengthDataset(BaseWrapperDataset): + """ + Bucket and pad item lengths to the nearest bucket size. This can be used to + reduce the number of unique batch shapes, which is important on TPUs since + each new batch shape requires a recompilation. + + Args: + dataset (FairseqDatset): dataset to bucket + sizes (List[int]): all item sizes + num_buckets (int): number of buckets to create + pad_idx (int): padding symbol + left_pad (bool): if True, pad on the left; otherwise right pad + """ + + def __init__( + self, + dataset, + sizes, + num_buckets, + pad_idx, + left_pad, + tensor_key=None, + ): + super().__init__(dataset) + self.pad_idx = pad_idx + self.left_pad = left_pad + + assert num_buckets > 0 + self.buckets = get_buckets(sizes, num_buckets) + self._bucketed_sizes = get_bucketed_sizes(sizes, self.buckets) + self._tensor_key = tensor_key + + def _set_tensor(self, item, val): + if self._tensor_key is None: + return val + item[self._tensor_key] = val + return item + + def _get_tensor(self, item): + if self._tensor_key is None: + return item + return item[self._tensor_key] + + def _pad(self, tensor, bucket_size, dim=-1): + num_pad = bucket_size - tensor.size(dim) + return F.pad( + tensor, + (num_pad if self.left_pad else 0, 0 if self.left_pad else num_pad), + value=self.pad_idx, + ) + + def __getitem__(self, index): + item = self.dataset[index] + bucket_size = self._bucketed_sizes[index] + tensor = self._get_tensor(item) + padded = self._pad(tensor, bucket_size) + return self._set_tensor(item, padded) + + @property + def sizes(self): + return self._bucketed_sizes + + def num_tokens(self, index): + return self._bucketed_sizes[index] + + def size(self, index): + return self._bucketed_sizes[index] diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/codedataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/codedataset.py new file mode 100644 index 00000000..a4330919 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/codedataset.py @@ -0,0 +1,576 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +import json +import logging +import os +import random +from pathlib import Path + +import numpy as np +import torch +import torch.utils.data + +from . import data_utils +from fairseq.data.fairseq_dataset import FairseqDataset + +F0_FRAME_SPACE = 0.005 # sec + + +logger = logging.getLogger(__name__) + + +class ExpressiveCodeDataConfig(object): + def __init__(self, json_path): + with open(json_path, "r") as f: + self.config = json.load(f) + self._manifests = self.config["manifests"] + + @property + def manifests(self): + return self._manifests + + @property + def n_units(self): + return self.config["n_units"] + + @property + def sampling_rate(self): + return self.config["sampling_rate"] + + @property + def code_hop_size(self): + return self.config["code_hop_size"] + + @property + def f0_stats(self): + """pre-computed f0 statistics path""" + return self.config.get("f0_stats", None) + + @property + def f0_vq_type(self): + """naive or precomp""" + return self.config["f0_vq_type"] + + @property + def f0_vq_name(self): + return self.config["f0_vq_name"] + + def get_f0_vq_naive_quantizer(self, log, norm_mean, norm_std): + key = "log" if log else "linear" + if norm_mean and norm_std: + key += "_mean_std_norm" + elif norm_mean: + key += "_mean_norm" + else: + key += "_none_norm" + return self.config["f0_vq_naive_quantizer"][key] + + @property + def f0_vq_n_units(self): + return self.config["f0_vq_n_units"] + + @property + def multispkr(self): + """how to parse speaker label from audio path""" + return self.config.get("multispkr", None) + + +def get_f0(audio, rate=16000): + try: + import amfm_decompy.basic_tools as basic + import amfm_decompy.pYAAPT as pYAAPT + from librosa.util import normalize + except ImportError: + raise "Please install amfm_decompy (`pip install AMFM-decompy`) and librosa (`pip install librosa`)." + + assert audio.ndim == 1 + frame_length = 20.0 # ms + to_pad = int(frame_length / 1000 * rate) // 2 + + audio = normalize(audio) * 0.95 + audio = np.pad(audio, (to_pad, to_pad), "constant", constant_values=0) + audio = basic.SignalObj(audio, rate) + pitch = pYAAPT.yaapt( + audio, + frame_length=frame_length, + frame_space=F0_FRAME_SPACE * 1000, + nccf_thresh1=0.25, + tda_frame_length=25.0, + ) + f0 = pitch.samp_values + return f0 + + +def interpolate_f0(f0): + try: + from scipy.interpolate import interp1d + except ImportError: + raise "Please install scipy (`pip install scipy`)" + + orig_t = np.arange(f0.shape[0]) + f0_interp = f0[:] + ii = f0_interp != 0 + if ii.sum() > 1: + f0_interp = interp1d( + orig_t[ii], f0_interp[ii], bounds_error=False, kind="linear", fill_value=0 + )(orig_t) + f0_interp = torch.Tensor(f0_interp).type_as(f0).to(f0.device) + return f0_interp + + +def naive_quantize(x, edges): + bin_idx = (x.view(-1, 1) > edges.view(1, -1)).long().sum(dim=1) + return bin_idx + + +def load_wav(full_path): + try: + import soundfile as sf + except ImportError: + raise "Please install soundfile (`pip install SoundFile`)" + data, sampling_rate = sf.read(full_path) + return data, sampling_rate + + +def parse_code(code_str, dictionary, append_eos): + code, duration = torch.unique_consecutive( + torch.ShortTensor(list(map(int, code_str.split()))), return_counts=True + ) + code = " ".join(map(str, code.tolist())) + code = dictionary.encode_line(code, append_eos).short() + + if append_eos: + duration = torch.cat((duration, duration.new_zeros((1,))), dim=0) # eos + duration = duration.short() + return code, duration + + +def parse_manifest(manifest, dictionary): + audio_files = [] + codes = [] + durations = [] + speakers = [] + + with open(manifest) as info: + for line in info.readlines(): + sample = eval(line.strip()) + if "cpc_km100" in sample: + k = "cpc_km100" + elif "hubert_km100" in sample: + k = "hubert_km100" + elif "phone" in sample: + k = "phone" + else: + assert False, "unknown format" + code = sample[k] + code, duration = parse_code(code, dictionary, append_eos=True) + + codes.append(code) + durations.append(duration) + audio_files.append(sample["audio"]) + speakers.append(sample.get("speaker", None)) + + return audio_files, codes, durations, speakers + + +def parse_speaker(path, method): + if type(path) == str: + path = Path(path) + + if method == "parent_name": + return path.parent.name + elif method == "parent_parent_name": + return path.parent.parent.name + elif method == "_": + return path.name.split("_")[0] + elif method == "single": + return "A" + elif callable(method): + return method(path) + else: + raise NotImplementedError() + + +def get_f0_by_filename(filename, tgt_sampling_rate): + audio, sampling_rate = load_wav(filename) + if sampling_rate != tgt_sampling_rate: + raise ValueError( + "{} SR doesn't match target {} SR".format(sampling_rate, tgt_sampling_rate) + ) + + # compute un-interpolated f0, and use Ann's interp in __getitem__ if set + f0 = get_f0(audio, rate=tgt_sampling_rate) + f0 = torch.from_numpy(f0.astype(np.float32)) + return f0 + + +def align_f0_to_durations(f0, durations, f0_code_ratio, tol=1): + code_len = durations.sum() + targ_len = int(f0_code_ratio * code_len) + diff = f0.size(0) - targ_len + assert abs(diff) <= tol, ( + f"Cannot subsample F0: |{f0.size(0)} - {f0_code_ratio}*{code_len}|" + f" > {tol} (dur=\n{durations})" + ) + if diff > 0: + f0 = f0[:targ_len] + elif diff < 0: + f0 = torch.cat((f0, f0.new_full((-diff,), f0[-1])), 0) + + f0_offset = 0.0 + seg_f0s = [] + for dur in durations: + f0_dur = dur.item() * f0_code_ratio + seg_f0 = f0[int(f0_offset) : int(f0_offset + f0_dur)] + seg_f0 = seg_f0[seg_f0 != 0] + if len(seg_f0) == 0: + seg_f0 = torch.tensor(0).type(seg_f0.type()) + else: + seg_f0 = seg_f0.mean() + seg_f0s.append(seg_f0) + f0_offset += f0_dur + + assert int(f0_offset) == f0.size(0), f"{f0_offset} {f0.size()} {durations.sum()}" + return torch.tensor(seg_f0s) + + +class Paddings(object): + def __init__(self, code_val, dur_val=0, f0_val=-2.0): + self.code = code_val + self.dur = dur_val + self.f0 = f0_val + + +class Shifts(object): + def __init__(self, shifts_str, pads): + self._shifts = list(map(int, shifts_str.split(","))) + assert len(self._shifts) == 2, self._shifts + assert all(s >= 0 for s in self._shifts) + self.extra_length = max(s for s in self._shifts) + self.pads = pads + + @property + def dur(self): + return self._shifts[0] + + @property + def f0(self): + return self._shifts[1] + + @staticmethod + def shift_one(seq, left_pad_num, right_pad_num, pad): + assert seq.ndim == 1 + bos = seq.new_full((left_pad_num,), pad) + eos = seq.new_full((right_pad_num,), pad) + seq = torch.cat([bos, seq, eos]) + mask = torch.ones_like(seq).bool() + mask[left_pad_num : len(seq) - right_pad_num] = 0 + return seq, mask + + def __call__(self, code, dur, f0): + if self.extra_length == 0: + code_mask = torch.zeros_like(code).bool() + dur_mask = torch.zeros_like(dur).bool() + f0_mask = torch.zeros_like(f0).bool() + return code, code_mask, dur, dur_mask, f0, f0_mask + + code, code_mask = self.shift_one(code, 0, self.extra_length, self.pads.code) + dur, dur_mask = self.shift_one( + dur, self.dur, self.extra_length - self.dur, self.pads.dur + ) + f0, f0_mask = self.shift_one( + f0, self.f0, self.extra_length - self.f0, self.pads.f0 + ) + return code, code_mask, dur, dur_mask, f0, f0_mask + + +class CodeDataset(FairseqDataset): + def __init__( + self, + manifest, + dictionary, + dur_dictionary, + f0_dictionary, + config, + discrete_dur, + discrete_f0, + log_f0, + normalize_f0_mean, + normalize_f0_std, + interpolate_f0, + return_filename=False, + strip_filename=True, + shifts="0,0", + return_continuous_f0=False, + ): + random.seed(1234) + self.dictionary = dictionary + self.dur_dictionary = dur_dictionary + self.f0_dictionary = f0_dictionary + self.config = config + + # duration config + self.discrete_dur = discrete_dur + + # pitch config + self.discrete_f0 = discrete_f0 + self.log_f0 = log_f0 + self.normalize_f0_mean = normalize_f0_mean + self.normalize_f0_std = normalize_f0_std + self.interpolate_f0 = interpolate_f0 + + self.return_filename = return_filename + self.strip_filename = strip_filename + self.f0_code_ratio = config.code_hop_size / ( + config.sampling_rate * F0_FRAME_SPACE + ) + + # use lazy loading to avoid sharing file handlers across workers + self.manifest = manifest + self._codes = None + self._durs = None + self._f0s = None + with open(f"{manifest}.leng.txt", "r") as f: + lengs = [int(line.rstrip()) for line in f] + edges = np.cumsum([0] + lengs) + self.starts, self.ends = edges[:-1], edges[1:] + with open(f"{manifest}.path.txt", "r") as f: + self.file_names = [line.rstrip() for line in f] + logger.info(f"num entries: {len(self.starts)}") + + if os.path.exists(f"{manifest}.f0_stat.pt"): + self.f0_stats = torch.load(f"{manifest}.f0_stat.pt") + elif config.f0_stats: + self.f0_stats = torch.load(config.f0_stats) + + self.multispkr = config.multispkr + if config.multispkr: + with open(f"{manifest}.speaker.txt", "r") as f: + self.spkrs = [line.rstrip() for line in f] + self.id_to_spkr = sorted(self.spkrs) + self.spkr_to_id = {k: v for v, k in enumerate(self.id_to_spkr)} + + self.pads = Paddings( + dictionary.pad(), + 0, # use 0 for duration padding + f0_dictionary.pad() if discrete_f0 else -5.0, + ) + self.shifts = Shifts(shifts, pads=self.pads) + self.return_continuous_f0 = return_continuous_f0 + + def get_data_handlers(self): + logging.info(f"loading data for {self.manifest}") + self._codes = np.load(f"{self.manifest}.code.npy", mmap_mode="r") + self._durs = np.load(f"{self.manifest}.dur.npy", mmap_mode="r") + + if self.discrete_f0: + if self.config.f0_vq_type == "precomp": + self._f0s = np.load( + f"{self.manifest}.{self.config.f0_vq_name}.npy", mmap_mode="r" + ) + elif self.config.f0_vq_type == "naive": + self._f0s = np.load(f"{self.manifest}.f0.npy", mmap_mode="r") + quantizers_path = self.config.get_f0_vq_naive_quantizer( + self.log_f0, self.normalize_f0_mean, self.normalize_f0_std + ) + quantizers = torch.load(quantizers_path) + n_units = self.config.f0_vq_n_units + self._f0_quantizer = torch.from_numpy(quantizers[n_units]) + else: + raise ValueError(f"f0_vq_type {self.config.f0_vq_type} not supported") + else: + self._f0s = np.load(f"{self.manifest}.f0.npy", mmap_mode="r") + + def preprocess_f0(self, f0, stats): + """ + 1. interpolate + 2. log transform (keep unvoiced frame 0) + """ + # TODO: change this to be dependent on config for naive quantizer + f0 = f0.clone() + if self.interpolate_f0: + f0 = interpolate_f0(f0) + + mask = f0 != 0 # only process voiced frames + if self.log_f0: + f0[mask] = f0[mask].log() + if self.normalize_f0_mean: + mean = stats["logf0_mean"] if self.log_f0 else stats["f0_mean"] + f0[mask] = f0[mask] - mean + if self.normalize_f0_std: + std = stats["logf0_std"] if self.log_f0 else stats["f0_std"] + f0[mask] = f0[mask] / std + return f0 + + def _get_raw_item(self, index): + start, end = self.starts[index], self.ends[index] + if self._codes is None: + self.get_data_handlers() + code = torch.from_numpy(np.array(self._codes[start:end])).long() + dur = torch.from_numpy(np.array(self._durs[start:end])) + f0 = torch.from_numpy(np.array(self._f0s[start:end])) + return code, dur, f0 + + def __getitem__(self, index): + code, dur, f0 = self._get_raw_item(index) + code = torch.cat([code.new([self.dictionary.bos()]), code]) + + # use 0 for eos and bos + dur = torch.cat([dur.new([0]), dur]) + if self.discrete_dur: + dur = self.dur_dictionary.encode_line( + " ".join(map(str, dur.tolist())), append_eos=False + ).long() + else: + dur = dur.float() + + # TODO: find a more elegant approach + raw_f0 = None + if self.discrete_f0: + if self.config.f0_vq_type == "precomp": + f0 = self.f0_dictionary.encode_line( + " ".join(map(str, f0.tolist())), append_eos=False + ).long() + else: + f0 = f0.float() + f0 = self.preprocess_f0(f0, self.f0_stats[self.spkrs[index]]) + if self.return_continuous_f0: + raw_f0 = f0 + raw_f0 = torch.cat([raw_f0.new([self.f0_dictionary.bos()]), raw_f0]) + f0 = naive_quantize(f0, self._f0_quantizer) + f0 = torch.cat([f0.new([self.f0_dictionary.bos()]), f0]) + else: + f0 = f0.float() + if self.multispkr: + f0 = self.preprocess_f0(f0, self.f0_stats[self.spkrs[index]]) + else: + f0 = self.preprocess_f0(f0, self.f0_stats) + f0 = torch.cat([f0.new([0]), f0]) + + if raw_f0 is not None: + *_, raw_f0, raw_f0_mask = self.shifts(code, dur, raw_f0) + else: + raw_f0_mask = None + + code, code_mask, dur, dur_mask, f0, f0_mask = self.shifts(code, dur, f0) + if raw_f0_mask is not None: + assert (raw_f0_mask == f0_mask).all() + + # is a padded frame if either input or output is padded + feats = { + "source": code[:-1], + "target": code[1:], + "mask": code_mask[1:].logical_or(code_mask[:-1]), + "dur_source": dur[:-1], + "dur_target": dur[1:], + "dur_mask": dur_mask[1:].logical_or(dur_mask[:-1]), + "f0_source": f0[:-1], + "f0_target": f0[1:], + "f0_mask": f0_mask[1:].logical_or(f0_mask[:-1]), + } + + if raw_f0 is not None: + feats["raw_f0"] = raw_f0[1:] + + if self.return_filename: + fname = self.file_names[index] + feats["filename"] = ( + fname if not self.strip_filename else Path(fname).with_suffix("").name + ) + return feats + + def __len__(self): + return len(self.starts) + + def size(self, index): + return self.ends[index] - self.starts[index] + self.shifts.extra_length + + def num_tokens(self, index): + return self.size(index) + + def collater(self, samples): + pad_idx, eos_idx = self.dictionary.pad(), self.dictionary.eos() + if len(samples) == 0: + return {} + + src_tokens = data_utils.collate_tokens( + [s["source"] for s in samples], pad_idx, eos_idx, left_pad=False + ) + + tgt_tokens = data_utils.collate_tokens( + [s["target"] for s in samples], + pad_idx=pad_idx, + eos_idx=pad_idx, # appending padding, eos is there already + left_pad=False, + ) + + src_durs, tgt_durs = [ + data_utils.collate_tokens( + [s[k] for s in samples], + pad_idx=self.pads.dur, + eos_idx=self.pads.dur, + left_pad=False, + ) + for k in ["dur_source", "dur_target"] + ] + + src_f0s, tgt_f0s = [ + data_utils.collate_tokens( + [s[k] for s in samples], + pad_idx=self.pads.f0, + eos_idx=self.pads.f0, + left_pad=False, + ) + for k in ["f0_source", "f0_target"] + ] + + mask, dur_mask, f0_mask = [ + data_utils.collate_tokens( + [s[k] for s in samples], + pad_idx=1, + eos_idx=1, + left_pad=False, + ) + for k in ["mask", "dur_mask", "f0_mask"] + ] + + src_lengths = torch.LongTensor([s["source"].numel() for s in samples]) + n_tokens = sum(len(s["source"]) for s in samples) + + result = { + "nsentences": len(samples), + "ntokens": n_tokens, + "net_input": { + "src_tokens": src_tokens, + "src_lengths": src_lengths, + "dur_src": src_durs, + "f0_src": src_f0s, + }, + "target": tgt_tokens, + "dur_target": tgt_durs, + "f0_target": tgt_f0s, + "mask": mask, + "dur_mask": dur_mask, + "f0_mask": f0_mask, + } + + if "filename" in samples[0]: + result["filename"] = [s["filename"] for s in samples] + + # TODO: remove this hack into the inference dataset + if "prefix" in samples[0]: + result["prefix"] = [s["prefix"] for s in samples] + + if "raw_f0" in samples[0]: + raw_f0s = data_utils.collate_tokens( + [s["raw_f0"] for s in samples], + pad_idx=self.pads.f0, + eos_idx=self.pads.f0, + left_pad=False, + ) + result["raw_f0"] = raw_f0s + return result diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/colorize_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/colorize_dataset.py new file mode 100644 index 00000000..7a6d2713 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/colorize_dataset.py @@ -0,0 +1,25 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +from . import BaseWrapperDataset + + +class ColorizeDataset(BaseWrapperDataset): + """Adds 'colors' property to net input that is obtained from the provided color getter for use by models""" + + def __init__(self, dataset, color_getter): + super().__init__(dataset) + self.color_getter = color_getter + + def collater(self, samples): + base_collate = super().collater(samples) + if len(base_collate) > 0: + base_collate["net_input"]["colors"] = torch.tensor( + list(self.color_getter(self.dataset, s["id"]) for s in samples), + dtype=torch.long, + ) + return base_collate diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/concat_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/concat_dataset.py new file mode 100644 index 00000000..01a4078b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/concat_dataset.py @@ -0,0 +1,124 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import bisect + +import numpy as np +from torch.utils.data.dataloader import default_collate + +from . import FairseqDataset + + +class ConcatDataset(FairseqDataset): + @staticmethod + def cumsum(sequence, sample_ratios): + r, s = [], 0 + for e, ratio in zip(sequence, sample_ratios): + curr_len = int(ratio * len(e)) + r.append(curr_len + s) + s += curr_len + return r + + def __init__(self, datasets, sample_ratios=1): + super(ConcatDataset, self).__init__() + assert len(datasets) > 0, "datasets should not be an empty iterable" + self.datasets = list(datasets) + if isinstance(sample_ratios, int): + sample_ratios = [sample_ratios] * len(self.datasets) + self.sample_ratios = sample_ratios + self.cumulative_sizes = self.cumsum(self.datasets, sample_ratios) + self.real_sizes = [len(d) for d in self.datasets] + + def __len__(self): + return self.cumulative_sizes[-1] + + def __getitem__(self, idx): + dataset_idx, sample_idx = self._get_dataset_and_sample_index(idx) + return self.datasets[dataset_idx][sample_idx] + + def _get_dataset_and_sample_index(self, idx: int): + dataset_idx = bisect.bisect_right(self.cumulative_sizes, idx) + if dataset_idx == 0: + sample_idx = idx + else: + sample_idx = idx - self.cumulative_sizes[dataset_idx - 1] + sample_idx = sample_idx % self.real_sizes[dataset_idx] + return dataset_idx, sample_idx + + def collater(self, samples, **extra_args): + # For now only supports datasets with same underlying collater implementations + if hasattr(self.datasets[0], "collater"): + return self.datasets[0].collater(samples, **extra_args) + else: + return default_collate(samples, **extra_args) + + def size(self, idx: int): + """ + Return an example's size as a float or tuple. + """ + dataset_idx, sample_idx = self._get_dataset_and_sample_index(idx) + return self.datasets[dataset_idx].size(sample_idx) + + def num_tokens(self, index: int): + return np.max(self.size(index)) + + def attr(self, attr: str, index: int): + dataset_idx = bisect.bisect_right(self.cumulative_sizes, index) + return getattr(self.datasets[dataset_idx], attr, None) + + @property + def sizes(self): + _dataset_sizes = [] + for ds, sr in zip(self.datasets, self.sample_ratios): + if isinstance(ds.sizes, np.ndarray): + _dataset_sizes.append(np.tile(ds.sizes, sr)) + else: + # Only support underlying dataset with single size array. + assert isinstance(ds.sizes, list) + _dataset_sizes.append(np.tile(ds.sizes[0], sr)) + return np.concatenate(_dataset_sizes) + + @property + def supports_prefetch(self): + return all(d.supports_prefetch for d in self.datasets) + + def ordered_indices(self): + """ + Returns indices sorted by length. So less padding is needed. + """ + if isinstance(self.sizes, np.ndarray) and len(self.sizes.shape) > 1: + # special handling for concatenating lang_pair_datasets + indices = np.arange(len(self)) + sizes = self.sizes + tgt_sizes = ( + sizes[:, 1] if len(sizes.shape) > 0 and sizes.shape[1] > 1 else None + ) + src_sizes = ( + sizes[:, 0] if len(sizes.shape) > 0 and sizes.shape[1] > 1 else sizes + ) + # sort by target length, then source length + if tgt_sizes is not None: + indices = indices[np.argsort(tgt_sizes[indices], kind="mergesort")] + return indices[np.argsort(src_sizes[indices], kind="mergesort")] + else: + return np.argsort(self.sizes) + + def prefetch(self, indices): + frm = 0 + for to, ds in zip(self.cumulative_sizes, self.datasets): + real_size = len(ds) + if getattr(ds, "supports_prefetch", False): + ds.prefetch([(i - frm) % real_size for i in indices if frm <= i < to]) + frm = to + + @property + def can_reuse_epoch_itr_across_epochs(self): + return all(d.can_reuse_epoch_itr_across_epochs for d in self.datasets) + + def set_epoch(self, epoch): + super().set_epoch(epoch) + for ds in self.datasets: + if hasattr(ds, "set_epoch"): + ds.set_epoch(epoch) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/concat_sentences_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/concat_sentences_dataset.py new file mode 100644 index 00000000..625a2937 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/concat_sentences_dataset.py @@ -0,0 +1,54 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +from . import FairseqDataset + + +class ConcatSentencesDataset(FairseqDataset): + def __init__(self, *datasets): + super().__init__() + self.datasets = datasets + assert all( + len(ds) == len(datasets[0]) for ds in datasets + ), "datasets must have the same length" + + def __getitem__(self, index): + return torch.cat([ds[index] for ds in self.datasets]) + + def __len__(self): + return len(self.datasets[0]) + + def collater(self, samples): + return self.datasets[0].collater(samples) + + @property + def sizes(self): + return sum(ds.sizes for ds in self.datasets) + + def num_tokens(self, index): + return sum(ds.num_tokens(index) for ds in self.datasets) + + def size(self, index): + return sum(ds.size(index) for ds in self.datasets) + + def ordered_indices(self): + return self.datasets[0].ordered_indices() + + @property + def supports_prefetch(self): + return any(getattr(ds, "supports_prefetch", False) for ds in self.datasets) + + def prefetch(self, indices): + for ds in self.datasets: + if getattr(ds, "supports_prefetch", False): + ds.prefetch(indices) + + def set_epoch(self, epoch): + super().set_epoch(epoch) + for ds in self.datasets: + if hasattr(ds, "set_epoch"): + ds.set_epoch(epoch) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/data_utils.py b/PyTorch/NLP/new-Transformer/fairseq/data/data_utils.py new file mode 100644 index 00000000..0372d52b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/data_utils.py @@ -0,0 +1,604 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +try: + from collections.abc import Iterable +except ImportError: + from collections import Iterable +import contextlib +import itertools +import logging +import re +import warnings +from typing import Optional, Tuple + +import numpy as np +import torch + +from fairseq.file_io import PathManager +from fairseq import utils +import os + +logger = logging.getLogger(__name__) + + +def infer_language_pair(path): + """Infer language pair from filename: .-.(...).idx""" + src, dst = None, None + for filename in PathManager.ls(path): + parts = filename.split(".") + if len(parts) >= 3 and len(parts[1].split("-")) == 2: + return parts[1].split("-") + return src, dst + + +def collate_tokens( + values, + pad_idx, + eos_idx=None, + left_pad=False, + move_eos_to_beginning=False, + pad_to_length=None, + pad_to_multiple=1, + pad_to_bsz=None, +): + """Convert a list of 1d tensors into a padded 2d tensor.""" + size = max(v.size(0) for v in values) + size = size if pad_to_length is None else max(size, pad_to_length) + if pad_to_multiple != 1 and size % pad_to_multiple != 0: + size = int(((size - 0.1) // pad_to_multiple + 1) * pad_to_multiple) + + batch_size = len(values) if pad_to_bsz is None else max(len(values), pad_to_bsz) + res = values[0].new(batch_size, size).fill_(pad_idx) + + def copy_tensor(src, dst): + assert dst.numel() == src.numel() + if move_eos_to_beginning: + if eos_idx is None: + # if no eos_idx is specified, then use the last token in src + dst[0] = src[-1] + else: + dst[0] = eos_idx + dst[1:] = src[:-1] + else: + dst.copy_(src) + + for i, v in enumerate(values): + copy_tensor(v, res[i][size - len(v) :] if left_pad else res[i][: len(v)]) + return res + + +def load_indexed_dataset( + path, dictionary=None, dataset_impl=None, combine=False, default="cached" +): + """A helper function for loading indexed datasets. + + Args: + path (str): path to indexed dataset (e.g., 'data-bin/train') + dictionary (~fairseq.data.Dictionary): data dictionary + dataset_impl (str, optional): which dataset implementation to use. If + not provided, it will be inferred automatically. For legacy indexed + data we use the 'cached' implementation by default. + combine (bool, optional): automatically load and combine multiple + datasets. For example, if *path* is 'data-bin/train', then we will + combine 'data-bin/train', 'data-bin/train1', ... and return a + single ConcatDataset instance. + """ + import fairseq.data.indexed_dataset as indexed_dataset + from fairseq.data.concat_dataset import ConcatDataset + + datasets = [] + for k in itertools.count(): + path_k = path + (str(k) if k > 0 else "") + try: + path_k = indexed_dataset.get_indexed_dataset_to_local(path_k) + except Exception as e: + if "StorageException: [404] Path not found" in str(e): + logger.warning(f"path_k: {e} not found") + else: + raise e + + dataset_impl_k = dataset_impl + if dataset_impl_k is None: + dataset_impl_k = indexed_dataset.infer_dataset_impl(path_k) + dataset = indexed_dataset.make_dataset( + path_k, + impl=dataset_impl_k or default, + fix_lua_indexing=True, + dictionary=dictionary, + ) + if dataset is None: + break + logger.info("loaded {:,} examples from: {}".format(len(dataset), path_k)) + datasets.append(dataset) + if not combine: + break + if len(datasets) == 0: + return None + elif len(datasets) == 1: + return datasets[0] + else: + return ConcatDataset(datasets) + + +@contextlib.contextmanager +def numpy_seed(seed, *addl_seeds): + """Context manager which seeds the NumPy PRNG with the specified seed and + restores the state afterward""" + if seed is None: + yield + return + if len(addl_seeds) > 0: + seed = int(hash((seed, *addl_seeds)) % 1e6) + state = np.random.get_state() + np.random.seed(seed) + try: + yield + finally: + np.random.set_state(state) + + +def collect_filtered(function, iterable, filtered): + """ + Similar to :func:`filter` but collects filtered elements in ``filtered``. + + Args: + function (callable): function that returns ``False`` for elements that + should be filtered + iterable (iterable): iterable to filter + filtered (list): list to store filtered elements + """ + for el in iterable: + if function(el): + yield el + else: + filtered.append(el) + + +def _filter_by_size_dynamic(indices, size_fn, max_positions, raise_exception=False): + def compare_leq(a, b): + return a <= b if not isinstance(a, tuple) else max(a) <= b + + def check_size(idx): + if isinstance(max_positions, float) or isinstance(max_positions, int): + return size_fn(idx) <= max_positions + elif isinstance(max_positions, dict): + idx_size = size_fn(idx) + assert isinstance(idx_size, dict) + intersect_keys = set(max_positions.keys()) & set(idx_size.keys()) + return all( + all( + a is None or b is None or a <= b + for a, b in zip(idx_size[key], max_positions[key]) + ) + for key in intersect_keys + ) + else: + # For MultiCorpusSampledDataset, will generalize it later + if not isinstance(size_fn(idx), Iterable): + return all(size_fn(idx) <= b for b in max_positions) + return all( + a is None or b is None or a <= b + for a, b in zip(size_fn(idx), max_positions) + ) + + ignored = [] + itr = collect_filtered(check_size, indices, ignored) + indices = np.fromiter(itr, dtype=np.int64, count=-1) + return indices, ignored + + +def filter_by_size(indices, dataset, max_positions, raise_exception=False): + """ + [deprecated] Filter indices based on their size. + Use `FairseqDataset::filter_indices_by_size` instead. + + Args: + indices (List[int]): ordered list of dataset indices + dataset (FairseqDataset): fairseq dataset instance + max_positions (tuple): filter elements larger than this size. + Comparisons are done component-wise. + raise_exception (bool, optional): if ``True``, raise an exception if + any elements are filtered (default: False). + """ + warnings.warn( + "data_utils.filter_by_size is deprecated. " + "Use `FairseqDataset::filter_indices_by_size` instead.", + stacklevel=2, + ) + if isinstance(max_positions, float) or isinstance(max_positions, int): + if hasattr(dataset, "sizes") and isinstance(dataset.sizes, np.ndarray): + ignored = indices[dataset.sizes[indices] > max_positions].tolist() + indices = indices[dataset.sizes[indices] <= max_positions] + elif ( + hasattr(dataset, "sizes") + and isinstance(dataset.sizes, list) + and len(dataset.sizes) == 1 + ): + ignored = indices[dataset.sizes[0][indices] > max_positions].tolist() + indices = indices[dataset.sizes[0][indices] <= max_positions] + else: + indices, ignored = _filter_by_size_dynamic( + indices, dataset.size, max_positions + ) + else: + indices, ignored = _filter_by_size_dynamic(indices, dataset.size, max_positions) + + if len(ignored) > 0 and raise_exception: + raise Exception( + ( + "Size of sample #{} is invalid (={}) since max_positions={}, " + "skip this example with --skip-invalid-size-inputs-valid-test" + ).format(ignored[0], dataset.size(ignored[0]), max_positions) + ) + if len(ignored) > 0: + logger.warning( + ( + "{} samples have invalid sizes and will be skipped, " + "max_positions={}, first few sample ids={}" + ).format(len(ignored), max_positions, ignored[:10]) + ) + return indices + + +def filter_paired_dataset_indices_by_size(src_sizes, tgt_sizes, indices, max_sizes): + """Filter a list of sample indices. Remove those that are longer + than specified in max_sizes. + + Args: + indices (np.array): original array of sample indices + max_sizes (int or list[int] or tuple[int]): max sample size, + can be defined separately for src and tgt (then list or tuple) + + Returns: + np.array: filtered sample array + list: list of removed indices + """ + if max_sizes is None: + return indices, [] + if type(max_sizes) in (int, float): + max_src_size, max_tgt_size = max_sizes, max_sizes + else: + max_src_size, max_tgt_size = max_sizes + if tgt_sizes is None: + ignored = indices[src_sizes[indices] > max_src_size] + else: + ignored = indices[ + (src_sizes[indices] > max_src_size) | (tgt_sizes[indices] > max_tgt_size) + ] + if len(ignored) > 0: + if tgt_sizes is None: + indices = indices[src_sizes[indices] <= max_src_size] + else: + indices = indices[ + (src_sizes[indices] <= max_src_size) + & (tgt_sizes[indices] <= max_tgt_size) + ] + return indices, ignored.tolist() + + +def batch_by_size( + indices, + num_tokens_fn, + num_tokens_vec=None, + max_tokens=None, + max_sentences=None, + required_batch_size_multiple=1, + fixed_shapes=None, +): + """ + Yield mini-batches of indices bucketed by size. Batches may contain + sequences of different lengths. + + Args: + indices (List[int]): ordered list of dataset indices + num_tokens_fn (callable): function that returns the number of tokens at + a given index + num_tokens_vec (List[int], optional): precomputed vector of the number + of tokens for each index in indices (to enable faster batch generation) + max_tokens (int, optional): max number of tokens in each batch + (default: None). + max_sentences (int, optional): max number of sentences in each + batch (default: None). + required_batch_size_multiple (int, optional): require batch size to + be less than N or a multiple of N (default: 1). + fixed_shapes (List[Tuple[int, int]], optional): if given, batches will + only be created with the given shapes. *max_sentences* and + *required_batch_size_multiple* will be ignored (default: None). + """ + try: + from fairseq.data.data_utils_fast import ( + batch_by_size_fn, + batch_by_size_vec, + batch_fixed_shapes_fast, + ) + except ImportError: + raise ImportError( + "Please build Cython components with: " + "`python setup.py build_ext --inplace`" + ) + except ValueError: + raise ValueError( + "Please build (or rebuild) Cython components with `python setup.py build_ext --inplace`." + ) + + # added int() to avoid TypeError: an integer is required + max_tokens = int(max_tokens) if max_tokens is not None else -1 + max_sentences = max_sentences if max_sentences is not None else -1 + bsz_mult = required_batch_size_multiple + + if not isinstance(indices, np.ndarray): + indices = np.fromiter(indices, dtype=np.int64, count=-1) + + if num_tokens_vec is not None and not isinstance(num_tokens_vec, np.ndarray): + num_tokens_vec = np.fromiter(num_tokens_vec, dtype=np.int64, count=-1) + + if fixed_shapes is None: + if num_tokens_vec is None: + return batch_by_size_fn( + indices, + num_tokens_fn, + max_tokens, + max_sentences, + bsz_mult, + ) + else: + return batch_by_size_vec( + indices, + num_tokens_vec, + max_tokens, + max_sentences, + bsz_mult, + ) + + else: + fixed_shapes = np.array(fixed_shapes, dtype=np.int64) + sort_order = np.lexsort( + [ + fixed_shapes[:, 1].argsort(), # length + fixed_shapes[:, 0].argsort(), # bsz + ] + ) + fixed_shapes_sorted = fixed_shapes[sort_order] + return batch_fixed_shapes_fast(indices, num_tokens_fn, fixed_shapes_sorted) + + +def post_process(sentence: str, symbol: str): + if symbol == "sentencepiece": + sentence = sentence.replace(" ", "").replace("\u2581", " ").strip() + elif symbol == "wordpiece": + sentence = sentence.replace(" ", "").replace("_", " ").strip() + elif symbol == "letter": + sentence = sentence.replace(" ", "").replace("|", " ").strip() + elif symbol == "silence": + import re + + sentence = sentence.replace("", "") + sentence = re.sub(" +", " ", sentence).strip() + elif symbol == "_EOW": + sentence = sentence.replace(" ", "").replace("_EOW", " ").strip() + elif symbol in {"subword_nmt", "@@ ", "@@"}: + if symbol == "subword_nmt": + symbol = "@@ " + sentence = (sentence + " ").replace(symbol, "").rstrip() + elif symbol == "none": + pass + elif symbol is not None: + raise NotImplementedError(f"Unknown post_process option: {symbol}") + return sentence + + +def compute_mask_indices( + shape: Tuple[int, int], + padding_mask: Optional[torch.Tensor], + mask_prob: float, + mask_length: int, + mask_type: str = "static", + mask_other: float = 0.0, + min_masks: int = 0, + no_overlap: bool = False, + min_space: int = 0, + require_same_masks: bool = True, + mask_dropout: float = 0.0, +) -> np.ndarray: + """ + Computes random mask spans for a given shape + + Args: + shape: the the shape for which to compute masks. + should be of size 2 where first element is batch size and 2nd is timesteps + padding_mask: optional padding mask of the same size as shape, which will prevent masking padded elements + mask_prob: probability for each token to be chosen as start of the span to be masked. this will be multiplied by + number of timesteps divided by length of mask span to mask approximately this percentage of all elements. + however due to overlaps, the actual number will be smaller (unless no_overlap is True) + mask_type: how to compute mask lengths + static = fixed size + uniform = sample from uniform distribution [mask_other, mask_length*2] + normal = sample from normal distribution with mean mask_length and stdev mask_other. mask is min 1 element + poisson = sample from possion distribution with lambda = mask length + min_masks: minimum number of masked spans + no_overlap: if false, will switch to an alternative recursive algorithm that prevents spans from overlapping + min_space: only used if no_overlap is True, this is how many elements to keep unmasked between spans + require_same_masks: if true, will randomly drop out masks until same amount of masks remains in each sample + mask_dropout: randomly dropout this percentage of masks in each example + """ + + bsz, all_sz = shape + mask = np.full((bsz, all_sz), False) + + all_num_mask = int( + # add a random number for probabilistic rounding + mask_prob * all_sz / float(mask_length) + + np.random.rand() + ) + + all_num_mask = max(min_masks, all_num_mask) + + mask_idcs = [] + for i in range(bsz): + if padding_mask is not None: + sz = all_sz - padding_mask[i].long().sum().item() + num_mask = int( + # add a random number for probabilistic rounding + mask_prob * sz / float(mask_length) + + np.random.rand() + ) + num_mask = max(min_masks, num_mask) + else: + sz = all_sz + num_mask = all_num_mask + + if mask_type == "static": + lengths = np.full(num_mask, mask_length) + elif mask_type == "uniform": + lengths = np.random.randint(mask_other, mask_length * 2 + 1, size=num_mask) + elif mask_type == "normal": + lengths = np.random.normal(mask_length, mask_other, size=num_mask) + lengths = [max(1, int(round(x))) for x in lengths] + elif mask_type == "poisson": + lengths = np.random.poisson(mask_length, size=num_mask) + lengths = [int(round(x)) for x in lengths] + else: + raise Exception("unknown mask selection " + mask_type) + + if sum(lengths) == 0: + lengths[0] = min(mask_length, sz - 1) + + if no_overlap: + mask_idc = [] + + def arrange(s, e, length, keep_length): + span_start = np.random.randint(s, e - length) + mask_idc.extend(span_start + i for i in range(length)) + + new_parts = [] + if span_start - s - min_space >= keep_length: + new_parts.append((s, span_start - min_space + 1)) + if e - span_start - length - min_space > keep_length: + new_parts.append((span_start + length + min_space, e)) + return new_parts + + parts = [(0, sz)] + min_length = min(lengths) + for length in sorted(lengths, reverse=True): + lens = np.fromiter( + (e - s if e - s >= length + min_space else 0 for s, e in parts), + np.int, + ) + l_sum = np.sum(lens) + if l_sum == 0: + break + probs = lens / np.sum(lens) + c = np.random.choice(len(parts), p=probs) + s, e = parts.pop(c) + parts.extend(arrange(s, e, length, min_length)) + mask_idc = np.asarray(mask_idc) + else: + min_len = min(lengths) + if sz - min_len <= num_mask: + min_len = sz - num_mask - 1 + + mask_idc = np.random.choice(sz - min_len, num_mask, replace=False) + + mask_idc = np.asarray( + [ + mask_idc[j] + offset + for j in range(len(mask_idc)) + for offset in range(lengths[j]) + ] + ) + + mask_idcs.append(np.unique(mask_idc[mask_idc < sz])) + + min_len = min([len(m) for m in mask_idcs]) + for i, mask_idc in enumerate(mask_idcs): + if len(mask_idc) > min_len and require_same_masks: + mask_idc = np.random.choice(mask_idc, min_len, replace=False) + if mask_dropout > 0: + num_holes = np.rint(len(mask_idc) * mask_dropout).astype(int) + mask_idc = np.random.choice( + mask_idc, len(mask_idc) - num_holes, replace=False + ) + + mask[i, mask_idc] = True + + return mask + + +def get_mem_usage(): + try: + import psutil + + mb = 1024 * 1024 + return f"used={psutil.virtual_memory().used / mb}Mb; avail={psutil.virtual_memory().available / mb}Mb" + except ImportError: + return "N/A" + + +# lens: torch.LongTensor +# returns: torch.BoolTensor +def lengths_to_padding_mask(lens): + bsz, max_lens = lens.size(0), torch.max(lens).item() + mask = torch.arange(max_lens).to(lens.device).view(1, max_lens) + mask = mask.expand(bsz, -1) >= lens.view(bsz, 1).expand(-1, max_lens) + return mask + + +# lens: torch.LongTensor +# returns: torch.BoolTensor +def lengths_to_mask(lens): + return ~lengths_to_padding_mask(lens) + + +def get_buckets(sizes, num_buckets): + buckets = np.unique( + np.percentile( + sizes, + np.linspace(0, 100, num_buckets + 1), + interpolation="lower", + )[1:] + ) + return buckets + + +def get_bucketed_sizes(orig_sizes, buckets): + sizes = np.copy(orig_sizes) + assert np.min(sizes) >= 0 + start_val = -1 + for end_val in buckets: + mask = (sizes > start_val) & (sizes <= end_val) + sizes[mask] = end_val + start_val = end_val + return sizes + + +def _find_extra_valid_paths(dataset_path: str) -> set: + paths = utils.split_paths(dataset_path) + all_valid_paths = set() + for sub_dir in paths: + contents = PathManager.ls(sub_dir) + valid_paths = [c for c in contents if re.match("valid*[0-9].*", c) is not None] + all_valid_paths |= {os.path.basename(p) for p in valid_paths} + # Remove .bin, .idx etc + roots = {os.path.splitext(p)[0] for p in all_valid_paths} + return roots + + +def raise_if_valid_subsets_unintentionally_ignored(train_cfg) -> None: + """Raises if there are paths matching 'valid*[0-9].*' which are not combined or ignored.""" + if ( + train_cfg.dataset.ignore_unused_valid_subsets + or train_cfg.dataset.combine_valid_subsets + or train_cfg.dataset.disable_validation + or not hasattr(train_cfg.task, "data") + ): + return + other_paths = _find_extra_valid_paths(train_cfg.task.data) + specified_subsets = train_cfg.dataset.valid_subset.split(",") + ignored_paths = [p for p in other_paths if p not in specified_subsets] + if ignored_paths: + advice = "Set --combine-val to combine them or --ignore-unused-valid-subsets to ignore them." + msg = f"Valid paths {ignored_paths} will be ignored. {advice}" + raise ValueError(msg) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/data_utils_fast.pyx b/PyTorch/NLP/new-Transformer/fairseq/data/data_utils_fast.pyx new file mode 100644 index 00000000..c61f31d6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/data_utils_fast.pyx @@ -0,0 +1,178 @@ +# cython: language_level=3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np + +cimport cython +cimport numpy as np + +from libc.stdint cimport int32_t, int64_t +from libcpp cimport bool as bool_t + +ctypedef int64_t DTYPE_t + +@cython.cdivision(True) +@cython.boundscheck(False) +@cython.wraparound(False) +cpdef list batch_by_size_vec( + np.ndarray[int64_t, ndim=1] indices, + np.ndarray[int64_t, ndim=1] num_tokens_vec, + int64_t max_tokens, + int64_t max_sentences, + int32_t bsz_mult, +): + if indices.shape[0] == 0: + return [] + + assert max_tokens <= 0 or np.max(num_tokens_vec) <= max_tokens, ( + f"Sentences lengths should not exceed max_tokens={max_tokens}" + ) + + cdef int32_t indices_len = indices.shape[0] + cdef np.ndarray[int32_t, ndim=1] batches_ends = \ + np.zeros(indices_len, dtype=np.int32) + cdef int32_t[:] batches_ends_view = batches_ends + cdef int64_t[:] num_tokens_view = num_tokens_vec + + cdef int32_t pos = 0 + cdef int32_t new_batch_end = 0 + + cdef int64_t new_batch_max_tokens = 0 + cdef int32_t new_batch_sentences = 0 + cdef int64_t new_batch_num_tokens = 0 + + cdef bool_t overflow = False + cdef bool_t size_matches_with_bsz_mult = False + + cdef int32_t batches_count = 0 + cdef int32_t batch_start = 0 + cdef int64_t tail_max_tokens = 0 + cdef int64_t batch_max_tokens = 0 + + for pos in range(indices_len): + # At every pos we keep stats about the last complete batch [batch_start:batch_end), + # and tail [batch_end:pos]. + # 1) Every time when (batch + tail) forms a valid batch + # (according to max_tokens, max_sentences and bsz_mult) we append tail to batch. + # 2) When (batch+tail) violates max_tokens or max_sentences constraints + # we finalize running batch, and tail becomes a new batch. + # 3) There is a corner case when tail also violates constraints. + # In that situation [batch_end:pos-1] (tail without the current pos) + # gets added to the finalized batches, while [pos:pos] becomes a new tail. + # + # Important: For the sake of performance try to avoid using function calls within this loop. + + tail_max_tokens = tail_max_tokens \ + if tail_max_tokens > num_tokens_view[pos] \ + else num_tokens_view[pos] + new_batch_end = pos + 1 + new_batch_max_tokens = batch_max_tokens \ + if batch_max_tokens > tail_max_tokens \ + else tail_max_tokens + new_batch_sentences = new_batch_end - batch_start + new_batch_num_tokens = new_batch_sentences * new_batch_max_tokens + + overflow = (new_batch_sentences > max_sentences > 0 or + new_batch_num_tokens > max_tokens > 0) + size_matches_with_bsz_mult = (new_batch_sentences < bsz_mult or + new_batch_sentences % bsz_mult == 0) + + if overflow: + tail_num_tokens = tail_max_tokens * \ + (new_batch_end - batches_ends_view[batches_count]) + tail_overflow = tail_num_tokens > max_tokens > 0 + # In case of a tail overflow finalize two batches + if tail_overflow: + batches_count += 1 + batches_ends_view[batches_count] = pos + tail_max_tokens = num_tokens_view[pos] + batch_start = batches_ends_view[batches_count] + batches_count += 1 + new_batch_max_tokens = tail_max_tokens + + if overflow or size_matches_with_bsz_mult: + batches_ends_view[batches_count] = new_batch_end + batch_max_tokens = new_batch_max_tokens + tail_max_tokens = 0 + if batches_ends_view[batches_count] != indices_len: + batches_count += 1 + # Memory and time-efficient split + return np.split(indices, batches_ends[:batches_count]) + + +@cython.boundscheck(False) +@cython.wraparound(False) +cpdef list batch_by_size_fn( + np.ndarray[DTYPE_t, ndim=1] indices, + num_tokens_fn, + int64_t max_tokens, + int64_t max_sentences, + int32_t bsz_mult, +): + cdef int32_t indices_len = indices.shape[0] + cdef np.ndarray[int64_t, ndim=1] num_tokens_vec = np.zeros(indices_len, + dtype=np.int64) + cdef DTYPE_t[:] indices_view = indices + cdef DTYPE_t[:] num_tokens_vec_view = num_tokens_vec + cdef int64_t pos + for pos in range(indices_len): + num_tokens_vec[pos] = num_tokens_fn(indices_view[pos]) + return batch_by_size_vec(indices, num_tokens_vec, max_tokens, + max_sentences, bsz_mult,) + + +cdef _find_valid_shape( + DTYPE_t[:, :] shapes_view, + int64_t num_sentences, + int64_t num_tokens, +): + """Return index of first valid shape of -1 if none is found.""" + for i in range(shapes_view.shape[0]): + if num_sentences <= shapes_view[i][0] and num_tokens <= shapes_view[i][1]: + return i + return -1 + + +@cython.cdivision(True) +cpdef list batch_fixed_shapes_fast( + np.ndarray[DTYPE_t, ndim=1] indices, + num_tokens_fn, + np.ndarray[DTYPE_t, ndim=2] fixed_shapes_sorted, +): + cdef int64_t sample_len = 0 + cdef list sample_lens = [] + cdef list batch = [] + cdef list batches = [] + cdef int64_t mod_len + cdef int64_t i + cdef int64_t idx + cdef int64_t num_tokens + cdef DTYPE_t[:] indices_view = indices + cdef DTYPE_t[:, :] shapes_view = fixed_shapes_sorted + + for i in range(len(indices_view)): + idx = indices_view[i] + num_tokens = num_tokens_fn(idx) + sample_lens.append(num_tokens) + sample_len = max(sample_len, num_tokens) + + shape_idx = _find_valid_shape(shapes_view, len(batch) + 1, sample_len) + if shape_idx == -1: + batches.append(batch) + batch = [] + sample_lens = [] + sample_len = 0 + shapes_view = fixed_shapes_sorted + elif shape_idx > 0: + # small optimization for the next call to _find_valid_shape + shapes_view = shapes_view[shape_idx:] + + batch.append(idx) + + if len(batch) > 0: + batches.append(batch) + + return batches diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/denoising_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/denoising_dataset.py new file mode 100644 index 00000000..bdb62c8d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/denoising_dataset.py @@ -0,0 +1,436 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import numpy as np +import torch + +from . import FairseqDataset, data_utils + + +def collate( + samples, + pad_idx, + eos_idx, + vocab, + left_pad_source=False, + left_pad_target=False, + input_feeding=True, + pad_to_length=None, +): + assert input_feeding + if len(samples) == 0: + return {} + + def merge(key, left_pad, move_eos_to_beginning=False, pad_to_length=None): + return data_utils.collate_tokens( + [s[key] for s in samples], + pad_idx, + eos_idx=None, # use eos_idx of each sample instead of vocab.eos() + left_pad=left_pad, + move_eos_to_beginning=move_eos_to_beginning, + pad_to_length=pad_to_length, + ) + + id = torch.LongTensor([s["id"] for s in samples]) + src_tokens = merge( + "source", + left_pad=left_pad_source, + pad_to_length=pad_to_length["source"] if pad_to_length is not None else None, + ) + # sort by descending source length + src_lengths = torch.LongTensor([s["source"].numel() for s in samples]) + src_lengths, sort_order = src_lengths.sort(descending=True) + id = id.index_select(0, sort_order) + src_tokens = src_tokens.index_select(0, sort_order) + + prev_output_tokens = None + target = None + if samples[0].get("target", None) is not None: + target = merge( + "target", + left_pad=left_pad_target, + pad_to_length=pad_to_length["target"] + if pad_to_length is not None + else None, + ) + target = target.index_select(0, sort_order) + ntokens = sum(len(s["target"]) for s in samples) + + if input_feeding: + # we create a shifted version of targets for feeding the + # previous output token(s) into the next decoder step + prev_output_tokens = merge( + "target", + left_pad=left_pad_target, + move_eos_to_beginning=True, + pad_to_length=pad_to_length["target"] + if pad_to_length is not None + else None, + ) + prev_output_tokens = prev_output_tokens.index_select(0, sort_order) + else: + ntokens = sum(len(s["source"]) for s in samples) + + batch = { + "id": id, + "ntokens": ntokens, + "net_input": { + "src_tokens": src_tokens, + "src_lengths": src_lengths, + }, + "target": target, + "nsentences": samples[0]["source"].size(0), + "sort_order": sort_order, + } + if prev_output_tokens is not None: + batch["net_input"]["prev_output_tokens"] = prev_output_tokens + + return batch + + +class DenoisingDataset(FairseqDataset): + """ + A wrapper around TokenBlockDataset for BART dataset. + + Args: + dataset (TokenBlockDataset): dataset to wrap + sizes (List[int]): sentence lengths + vocab (~fairseq.data.Dictionary): vocabulary + mask_idx (int): dictionary index used for masked token + mask_whole_words: only mask whole words. This should be a byte mask + over vocab indices, indicating whether it is the beginning of a + word. We will extend any mask to encompass the whole word. + shuffle (bool, optional): shuffle the elements before batching. + Default: ``True`` + seed: Seed for random number generator for reproducibility. + args: argparse arguments. + """ + + def __init__( + self, + dataset, + sizes, + vocab, + mask_idx, + mask_whole_words, + shuffle, + seed, + args, + eos=None, + item_transform_func=None, + ): + self.dataset = dataset + + self.sizes = sizes + + self.vocab = vocab + self.shuffle = shuffle + self.seed = seed + self.mask_idx = mask_idx + self.mask_whole_word = mask_whole_words + self.mask_ratio = args.mask + self.random_ratio = args.mask_random + self.insert_ratio = args.insert + self.rotate_ratio = args.rotate + self.permute_sentence_ratio = args.permute_sentences + self.eos = eos if eos is not None else vocab.eos() + self.item_transform_func = item_transform_func + + if args.bpe != "gpt2": + self.full_stop_index = self.vocab.eos() + else: + assert args.bpe == "gpt2" + self.full_stop_index = self.vocab.index("13") + + self.replace_length = args.replace_length + if self.replace_length not in [-1, 0, 1]: + raise ValueError(f"invalid arg: replace_length={self.replace_length}") + if args.mask_length not in ["subword", "word", "span-poisson"]: + raise ValueError(f"invalid arg: mask-length={args.mask_length}") + if args.mask_length == "subword" and args.replace_length not in [0, 1]: + raise ValueError(f"if using subwords, use replace-length=1 or 0") + + self.mask_span_distribution = None + if args.mask_length == "span-poisson": + _lambda = args.poisson_lambda + + lambda_to_the_k = 1 + e_to_the_minus_lambda = math.exp(-_lambda) + k_factorial = 1 + ps = [] + for k in range(0, 128): + ps.append(e_to_the_minus_lambda * lambda_to_the_k / k_factorial) + lambda_to_the_k *= _lambda + k_factorial *= k + 1 + if ps[-1] < 0.0000001: + break + ps = torch.FloatTensor(ps) + self.mask_span_distribution = torch.distributions.Categorical(ps) + + self.epoch = 0 + + @property + def can_reuse_epoch_itr_across_epochs(self): + return True # only the noise changes, not item sizes + + def set_epoch(self, epoch, **unused): + self.epoch = epoch + + def __getitem__(self, index): + with data_utils.numpy_seed(self.seed, self.epoch, index): + tokens = self.dataset[index] + assert tokens[-1] == self.eos + source, target = tokens, tokens.clone() + + if self.permute_sentence_ratio > 0.0: + source = self.permute_sentences(source, self.permute_sentence_ratio) + + if self.mask_ratio > 0: + source = self.add_whole_word_mask(source, self.mask_ratio) + + if self.insert_ratio > 0: + source = self.add_insertion_noise(source, self.insert_ratio) + + if self.rotate_ratio > 0.0 and np.random.random() < self.rotate_ratio: + source = self.add_rolling_noise(source) + # there can additional changes to make: + if self.item_transform_func is not None: + source, target = self.item_transform_func(source, target) + + assert (source >= 0).all() + assert (source[1:-1] >= 1).all() + assert (source <= len(self.vocab)).all() + assert source[0] == self.vocab.bos() + assert source[-1] == self.eos + return { + "id": index, + "source": source, + "target": target, + } + + def __len__(self): + return len(self.dataset) + + def permute_sentences(self, source, p=1.0): + full_stops = source == self.full_stop_index + # Pretend it ends with a full stop so last span is a sentence + full_stops[-2] = 1 + + # Tokens that are full stops, where the previous token is not + sentence_ends = (full_stops[1:] * ~full_stops[:-1]).nonzero(as_tuple=False) + 2 + result = source.clone() + + num_sentences = sentence_ends.size(0) + num_to_permute = math.ceil((num_sentences * 2 * p) / 2.0) + substitutions = torch.randperm(num_sentences)[:num_to_permute] + ordering = torch.arange(0, num_sentences) + ordering[substitutions] = substitutions[torch.randperm(num_to_permute)] + + # Ignore at start + index = 1 + for i in ordering: + sentence = source[(sentence_ends[i - 1] if i > 0 else 1) : sentence_ends[i]] + result[index : index + sentence.size(0)] = sentence + index += sentence.size(0) + return result + + def word_starts(self, source): + if self.mask_whole_word is not None: + is_word_start = self.mask_whole_word.gather(0, source) + else: + is_word_start = torch.ones(source.size()) + is_word_start[0] = 0 + is_word_start[-1] = 0 + return is_word_start + + def add_whole_word_mask(self, source, p): + is_word_start = self.word_starts(source) + num_to_mask = int(math.ceil(is_word_start.float().sum() * p)) + num_inserts = 0 + if num_to_mask == 0: + return source + + if self.mask_span_distribution is not None: + lengths = self.mask_span_distribution.sample(sample_shape=(num_to_mask,)) + + # Make sure we have enough to mask + cum_length = torch.cumsum(lengths, 0) + while cum_length[-1] < num_to_mask: + lengths = torch.cat( + [ + lengths, + self.mask_span_distribution.sample(sample_shape=(num_to_mask,)), + ], + dim=0, + ) + cum_length = torch.cumsum(lengths, 0) + + # Trim to masking budget + i = 0 + while cum_length[i] < num_to_mask: + i += 1 + lengths[i] = num_to_mask - (0 if i == 0 else cum_length[i - 1]) + num_to_mask = i + 1 + lengths = lengths[:num_to_mask] + + # Handle 0-length mask (inserts) separately + lengths = lengths[lengths > 0] + num_inserts = num_to_mask - lengths.size(0) + num_to_mask -= num_inserts + if num_to_mask == 0: + return self.add_insertion_noise(source, num_inserts / source.size(0)) + + assert (lengths > 0).all() + else: + lengths = torch.ones((num_to_mask,)).long() + assert is_word_start[-1] == 0 + word_starts = is_word_start.nonzero(as_tuple=False) + indices = word_starts[ + torch.randperm(word_starts.size(0))[:num_to_mask] + ].squeeze(1) + mask_random = torch.FloatTensor(num_to_mask).uniform_() < self.random_ratio + + source_length = source.size(0) + assert source_length - 1 not in indices + to_keep = torch.ones(source_length, dtype=torch.bool) + is_word_start[ + -1 + ] = 255 # acts as a long length, so spans don't go over the end of doc + if self.replace_length == 0: + to_keep[indices] = 0 + else: + # keep index, but replace it with [MASK] + source[indices] = self.mask_idx + source[indices[mask_random]] = torch.randint( + 1, len(self.vocab), size=(mask_random.sum(),) + ) + + if self.mask_span_distribution is not None: + assert len(lengths.size()) == 1 + assert lengths.size() == indices.size() + lengths -= 1 + while indices.size(0) > 0: + assert lengths.size() == indices.size() + lengths -= is_word_start[indices + 1].long() + uncompleted = lengths >= 0 + indices = indices[uncompleted] + 1 + mask_random = mask_random[uncompleted] + lengths = lengths[uncompleted] + if self.replace_length != -1: + # delete token + to_keep[indices] = 0 + else: + # keep index, but replace it with [MASK] + source[indices] = self.mask_idx + source[indices[mask_random]] = torch.randint( + 1, len(self.vocab), size=(mask_random.sum(),) + ) + else: + # A bit faster when all lengths are 1 + while indices.size(0) > 0: + uncompleted = is_word_start[indices + 1] == 0 + indices = indices[uncompleted] + 1 + mask_random = mask_random[uncompleted] + if self.replace_length != -1: + # delete token + to_keep[indices] = 0 + else: + # keep index, but replace it with [MASK] + source[indices] = self.mask_idx + source[indices[mask_random]] = torch.randint( + 1, len(self.vocab), size=(mask_random.sum(),) + ) + + assert source_length - 1 not in indices + + source = source[to_keep] + + if num_inserts > 0: + source = self.add_insertion_noise(source, num_inserts / source.size(0)) + + return source + + def add_permuted_noise(self, tokens, p): + num_words = len(tokens) + num_to_permute = math.ceil(((num_words * 2) * p) / 2.0) + substitutions = torch.randperm(num_words - 2)[:num_to_permute] + 1 + tokens[substitutions] = tokens[substitutions[torch.randperm(num_to_permute)]] + return tokens + + def add_rolling_noise(self, tokens): + offset = np.random.randint(1, max(1, tokens.size(-1) - 1) + 1) + tokens = torch.cat( + (tokens[0:1], tokens[offset:-1], tokens[1:offset], tokens[-1:]), + dim=0, + ) + return tokens + + def add_insertion_noise(self, tokens, p): + if p == 0.0: + return tokens + + num_tokens = len(tokens) + n = int(math.ceil(num_tokens * p)) + + noise_indices = torch.randperm(num_tokens + n - 2)[:n] + 1 + noise_mask = torch.zeros(size=(num_tokens + n,), dtype=torch.bool) + noise_mask[noise_indices] = 1 + result = torch.LongTensor(n + len(tokens)).fill_(-1) + + num_random = int(math.ceil(n * self.random_ratio)) + result[noise_indices[num_random:]] = self.mask_idx + result[noise_indices[:num_random]] = torch.randint( + low=1, high=len(self.vocab), size=(num_random,) + ) + + result[~noise_mask] = tokens + + assert (result >= 0).all() + return result + + def collater(self, samples, pad_to_length=None): + """Merge a list of samples to form a mini-batch. + Args: + samples (List[dict]): samples to collate + Returns: + dict: a mini-batch of data + """ + return collate( + samples, self.vocab.pad(), self.eos, self.vocab, pad_to_length=pad_to_length + ) + + def num_tokens(self, index): + """Return the number of tokens in a sample. This value is used to + enforce ``--max-tokens`` during batching.""" + return self.sizes[index] + + def size(self, index): + """Return an example's size as a float or tuple. This value is used when + filtering a dataset with ``--max-positions``.""" + return self.sizes[index] + + def ordered_indices(self): + """Return an ordered list of indices. Batches will be constructed based + on this order.""" + if self.shuffle: + indices = np.random.permutation(len(self)) + else: + indices = np.arange(len(self)) + return indices[np.argsort(self.sizes[indices], kind="mergesort")] + + def prefetch(self, indices): + self.src.prefetch(indices) + self.tgt.prefetch(indices) + + @property + def supports_prefetch(self): + return ( + hasattr(self.src, "supports_prefetch") + and self.src.supports_prefetch + and hasattr(self.tgt, "supports_prefetch") + and self.tgt.supports_prefetch + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/dictionary.py b/PyTorch/NLP/new-Transformer/fairseq/data/dictionary.py new file mode 100644 index 00000000..d6495389 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/dictionary.py @@ -0,0 +1,401 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import os +from collections import Counter +from multiprocessing import Pool + +import torch +from fairseq import utils +from fairseq.data import data_utils +from fairseq.file_chunker_utils import Chunker, find_offsets +from fairseq.file_io import PathManager +from fairseq.tokenizer import tokenize_line + + +class Dictionary: + """A mapping from symbols to consecutive integers""" + + def __init__( + self, + *, # begin keyword-only arguments + bos="", + pad="", + eos="", + unk="", + extra_special_symbols=None, + ): + self.bos_word, self.unk_word, self.pad_word, self.eos_word = bos, unk, pad, eos + self.symbols = [] + self.count = [] + self.indices = {} + self.bos_index = self.add_symbol(bos) + self.pad_index = self.add_symbol(pad) + self.eos_index = self.add_symbol(eos) + self.unk_index = self.add_symbol(unk) + if extra_special_symbols: + for s in extra_special_symbols: + self.add_symbol(s) + self.nspecial = len(self.symbols) + + def __eq__(self, other): + return self.indices == other.indices + + def __getitem__(self, idx): + if idx < len(self.symbols): + return self.symbols[idx] + return self.unk_word + + def get_count(self, idx): + return self.count[idx] + + def __len__(self): + """Returns the number of symbols in the dictionary""" + return len(self.symbols) + + def __contains__(self, sym): + return sym in self.indices + + def index(self, sym): + """Returns the index of the specified symbol""" + assert isinstance(sym, str) + if sym in self.indices: + return self.indices[sym] + return self.unk_index + + def string( + self, + tensor, + bpe_symbol=None, + escape_unk=False, + extra_symbols_to_ignore=None, + unk_string=None, + include_eos=False, + separator=" ", + ): + """Helper for converting a tensor of token indices to a string. + + Can optionally remove BPE symbols or escape words. + """ + if torch.is_tensor(tensor) and tensor.dim() == 2: + return "\n".join( + self.string( + t, + bpe_symbol, + escape_unk, + extra_symbols_to_ignore, + include_eos=include_eos, + ) + for t in tensor + ) + + extra_symbols_to_ignore = set(extra_symbols_to_ignore or []) + if not include_eos: + extra_symbols_to_ignore.add(self.eos()) + + def token_string(i): + if i == self.unk(): + if unk_string is not None: + return unk_string + else: + return self.unk_string(escape_unk) + else: + return self[i] + + if hasattr(self, "bos_index"): + extra_symbols_to_ignore.add(self.bos()) + + sent = separator.join( + token_string(i) + for i in tensor + if utils.item(i) not in extra_symbols_to_ignore + ) + + return data_utils.post_process(sent, bpe_symbol) + + def unk_string(self, escape=False): + """Return unknown string, optionally escaped as: <>""" + if escape: + return "<{}>".format(self.unk_word) + else: + return self.unk_word + + def add_symbol(self, word, n=1, overwrite=False): + """Adds a word to the dictionary""" + if word in self.indices and not overwrite: + idx = self.indices[word] + self.count[idx] = self.count[idx] + n + return idx + else: + idx = len(self.symbols) + self.indices[word] = idx + self.symbols.append(word) + self.count.append(n) + return idx + + def update(self, new_dict): + """Updates counts from new dictionary.""" + for word in new_dict.symbols: + idx2 = new_dict.indices[word] + if word in self.indices: + idx = self.indices[word] + self.count[idx] = self.count[idx] + new_dict.count[idx2] + else: + idx = len(self.symbols) + self.indices[word] = idx + self.symbols.append(word) + self.count.append(new_dict.count[idx2]) + + def finalize(self, threshold=-1, nwords=-1, padding_factor=8): + """Sort symbols by frequency in descending order, ignoring special ones. + + Args: + - threshold defines the minimum word count + - nwords defines the total number of words in the final dictionary, + including special symbols + - padding_factor can be used to pad the dictionary size to be a + multiple of 8, which is important on some hardware (e.g., Nvidia + Tensor Cores). + """ + if nwords <= 0: + nwords = len(self) + + new_indices = dict(zip(self.symbols[: self.nspecial], range(self.nspecial))) + new_symbols = self.symbols[: self.nspecial] + new_count = self.count[: self.nspecial] + + c = Counter( + dict( + sorted(zip(self.symbols[self.nspecial :], self.count[self.nspecial :])) + ) + ) + for symbol, count in c.most_common(nwords - self.nspecial): + if count >= threshold: + new_indices[symbol] = len(new_symbols) + new_symbols.append(symbol) + new_count.append(count) + else: + break + + assert len(new_symbols) == len(new_indices) + + self.count = list(new_count) + self.symbols = list(new_symbols) + self.indices = new_indices + + self.pad_to_multiple_(padding_factor) + + def pad_to_multiple_(self, padding_factor): + """Pad Dictionary size to be a multiple of *padding_factor*.""" + if padding_factor > 1: + i = 0 + while len(self) % padding_factor != 0: + symbol = "madeupword{:04d}".format(i) + self.add_symbol(symbol, n=0) + i += 1 + + def bos(self): + """Helper to get index of beginning-of-sentence symbol""" + return self.bos_index + + def pad(self): + """Helper to get index of pad symbol""" + return self.pad_index + + def eos(self): + """Helper to get index of end-of-sentence symbol""" + return self.eos_index + + def unk(self): + """Helper to get index of unk symbol""" + return self.unk_index + + @classmethod + def load(cls, f): + """Loads the dictionary from a text file with the format: + + ``` + + + ... + ``` + """ + d = cls() + d.add_from_file(f) + return d + + def add_from_file(self, f): + """ + Loads a pre-existing dictionary from a text file and adds its symbols + to this instance. + """ + if isinstance(f, str): + try: + with open(PathManager.get_local_path(f), "r", encoding="utf-8") as fd: + self.add_from_file(fd) + except FileNotFoundError as fnfe: + raise fnfe + except UnicodeError: + raise Exception( + "Incorrect encoding detected in {}, please " + "rebuild the dataset".format(f) + ) + return + + lines = f.readlines() + indices_start_line = self._load_meta(lines) + + for line in lines[indices_start_line:]: + try: + line, field = line.rstrip().rsplit(" ", 1) + if field == "#fairseq:overwrite": + overwrite = True + line, field = line.rsplit(" ", 1) + else: + overwrite = False + count = int(field) + word = line + if word in self and not overwrite: + raise RuntimeError( + "Duplicate word found when loading Dictionary: '{}'. " + "Duplicate words can overwrite earlier ones by adding the " + "#fairseq:overwrite flag at the end of the corresponding row " + "in the dictionary file. If using the Camembert model, please " + "download an updated copy of the model file.".format(word) + ) + self.add_symbol(word, n=count, overwrite=overwrite) + except ValueError: + raise ValueError( + f"Incorrect dictionary format, expected ' [flags]': \"{line}\"" + ) + + def _save(self, f, kv_iterator): + if isinstance(f, str): + PathManager.mkdirs(os.path.dirname(f)) + with PathManager.open(f, "w", encoding="utf-8") as fd: + return self.save(fd) + for k, v in kv_iterator: + print("{} {}".format(k, v), file=f) + + def _get_meta(self): + return [], [] + + def _load_meta(self, lines): + return 0 + + def save(self, f): + """Stores dictionary into a text file""" + ex_keys, ex_vals = self._get_meta() + self._save( + f, + zip( + ex_keys + self.symbols[self.nspecial :], + ex_vals + self.count[self.nspecial :], + ), + ) + + def dummy_sentence(self, length): + t = torch.Tensor(length).uniform_(self.nspecial + 1, len(self)).long() + t[-1] = self.eos() + return t + + def encode_line( + self, + line, + line_tokenizer=tokenize_line, + add_if_not_exist=True, + consumer=None, + append_eos=True, + reverse_order=False, + ) -> torch.IntTensor: + words = line_tokenizer(line) + if reverse_order: + words = list(reversed(words)) + nwords = len(words) + ids = torch.IntTensor(nwords + 1 if append_eos else nwords) + + for i, word in enumerate(words): + if add_if_not_exist: + idx = self.add_symbol(word) + else: + idx = self.index(word) + if consumer is not None: + consumer(word, idx) + ids[i] = idx + if append_eos: + ids[nwords] = self.eos_index + return ids + + @staticmethod + def _add_file_to_dictionary_single_worker( + filename, + tokenize, + eos_word, + start_offset, + end_offset, + ): + counter = Counter() + with Chunker(filename, start_offset, end_offset) as line_iterator: + for line in line_iterator: + for word in tokenize(line): + counter.update([word]) + counter.update([eos_word]) + return counter + + @staticmethod + def add_file_to_dictionary(filename, dict, tokenize, num_workers): + def merge_result(counter): + for w, c in sorted(counter.items()): + dict.add_symbol(w, c) + + local_file = PathManager.get_local_path(filename) + offsets = find_offsets(local_file, num_workers) + if num_workers > 1: + chunks = zip(offsets, offsets[1:]) + pool = Pool(processes=num_workers) + results = [] + for (start_offset, end_offset) in chunks: + results.append( + pool.apply_async( + Dictionary._add_file_to_dictionary_single_worker, + ( + local_file, + tokenize, + dict.eos_word, + start_offset, + end_offset, + ), + ) + ) + pool.close() + pool.join() + for r in results: + merge_result(r.get()) + else: + merge_result( + Dictionary._add_file_to_dictionary_single_worker( + local_file, tokenize, dict.eos_word, offsets[0], offsets[1] + ) + ) + + +class TruncatedDictionary(object): + def __init__(self, wrapped_dict, length): + self.__class__ = type( + wrapped_dict.__class__.__name__, + (self.__class__, wrapped_dict.__class__), + {}, + ) + self.__dict__ = wrapped_dict.__dict__ + self.wrapped_dict = wrapped_dict + self.length = min(len(self.wrapped_dict), length) + + def __len__(self): + return self.length + + def __getitem__(self, i): + if i < self.length: + return self.wrapped_dict[i] + return self.wrapped_dict.unk() diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/__init__.py new file mode 100644 index 00000000..7cbe00a1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/__init__.py @@ -0,0 +1,29 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +import importlib +import os + +from fairseq import registry + + +build_tokenizer, register_tokenizer, TOKENIZER_REGISTRY, _ = registry.setup_registry( + "--tokenizer", + default=None, +) + + +build_bpe, register_bpe, BPE_REGISTRY, _ = registry.setup_registry( + "--bpe", + default=None, +) + + +# automatically import any Python files in the encoders/ directory +for file in sorted(os.listdir(os.path.dirname(__file__))): + if file.endswith(".py") and not file.startswith("_"): + module = file[: file.find(".py")] + importlib.import_module("fairseq.data.encoders." + module) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/byte_bpe.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/byte_bpe.py new file mode 100644 index 00000000..31e3a062 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/byte_bpe.py @@ -0,0 +1,48 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from dataclasses import dataclass, field + +from fairseq import file_utils +from fairseq.data.encoders import register_bpe +from fairseq.data.encoders.byte_utils import ( + SPACE, + SPACE_ESCAPE, + byte_encode, + smart_byte_decode, +) +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class ByteBpeConfig(FairseqDataclass): + sentencepiece_model_path: str = field( + default="???", metadata={"help": "path to sentencepiece model"} + ) + + +@register_bpe("byte_bpe", dataclass=ByteBpeConfig) +class ByteBPE(object): + def __init__(self, cfg): + vocab = file_utils.cached_path(cfg.sentencepiece_model_path) + try: + import sentencepiece as spm + + self.sp = spm.SentencePieceProcessor() + self.sp.Load(vocab) + except ImportError: + raise ImportError( + "Please install sentencepiece with: pip install sentencepiece" + ) + + def encode(self, x: str) -> str: + byte_encoded = byte_encode(x) + return SPACE.join(self.sp.EncodeAsPieces(byte_encoded)) + + @staticmethod + def decode(x: str) -> str: + unescaped = x.replace(SPACE, "").replace(SPACE_ESCAPE, SPACE) + return smart_byte_decode(unescaped) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/byte_utils.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/byte_utils.py new file mode 100644 index 00000000..a305c080 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/byte_utils.py @@ -0,0 +1,51 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import re + + +WHITESPACE_NORMALIZER = re.compile(r"\s+") +SPACE = chr(32) +SPACE_ESCAPE = chr(9601) +# excluding non-breaking space (160) here +PRINTABLE_LATIN = set( + list(range(32, 126 + 1)) + list(range(161, 172 + 1)) + list(range(174, 255 + 1)) +) +BYTE_TO_BCHAR = { + b: chr(b) if b in PRINTABLE_LATIN else chr(256 + b) for b in range(256) +} +BCHAR_TO_BYTE = {bc: b for b, bc in BYTE_TO_BCHAR.items()} + + +def byte_encode(x: str) -> str: + normalized = WHITESPACE_NORMALIZER.sub(SPACE, x) + return "".join([BYTE_TO_BCHAR[b] for b in normalized.encode("utf-8")]) + + +def byte_decode(x: str) -> str: + try: + return bytes([BCHAR_TO_BYTE[bc] for bc in x]).decode("utf-8") + except ValueError: + return "" + + +def smart_byte_decode(x: str) -> str: + output = byte_decode(x) + if output == "": + # DP the best recovery (max valid chars) if it's broken + n_bytes = len(x) + f = [0 for _ in range(n_bytes + 1)] + pt = [0 for _ in range(n_bytes + 1)] + for i in range(1, n_bytes + 1): + f[i], pt[i] = f[i - 1], i - 1 + for j in range(1, min(4, i) + 1): + if f[i - j] + 1 > f[i] and len(byte_decode(x[i - j : i])) > 0: + f[i], pt[i] = f[i - j] + 1, i - j + cur_pt = n_bytes + while cur_pt > 0: + if f[cur_pt] == f[pt[cur_pt]] + 1: + output = byte_decode(x[pt[cur_pt] : cur_pt]) + output + cur_pt = pt[cur_pt] + return output diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/bytes.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/bytes.py new file mode 100644 index 00000000..f88f8f69 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/bytes.py @@ -0,0 +1,34 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from fairseq.data.encoders import register_bpe +from fairseq.data.encoders.byte_utils import ( + SPACE, + SPACE_ESCAPE, + byte_encode, + smart_byte_decode, +) + + +@register_bpe("bytes") +class Bytes(object): + def __init__(self, *unused): + pass + + @staticmethod + def add_args(parser): + pass + + @staticmethod + def encode(x: str) -> str: + encoded = byte_encode(x) + escaped = encoded.replace(SPACE, SPACE_ESCAPE) + return SPACE.join(list(escaped)) + + @staticmethod + def decode(x: str) -> str: + unescaped = x.replace(SPACE, "").replace(SPACE_ESCAPE, SPACE) + return smart_byte_decode(unescaped) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/characters.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/characters.py new file mode 100644 index 00000000..494ea219 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/characters.py @@ -0,0 +1,30 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from fairseq.data.encoders import register_bpe + + +SPACE = chr(32) +SPACE_ESCAPE = chr(9601) + + +@register_bpe("characters") +class Characters(object): + def __init__(self, *unused): + pass + + @staticmethod + def add_args(parser): + pass + + @staticmethod + def encode(x: str) -> str: + escaped = x.replace(SPACE, SPACE_ESCAPE) + return SPACE.join(list(escaped)) + + @staticmethod + def decode(x: str) -> str: + return x.replace(SPACE, "").replace(SPACE_ESCAPE, SPACE) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/fastbpe.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/fastbpe.py new file mode 100644 index 00000000..f7c21039 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/fastbpe.py @@ -0,0 +1,36 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field + +from fairseq import file_utils +from fairseq.data.encoders import register_bpe +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class fastBPEConfig(FairseqDataclass): + bpe_codes: str = field(default="???", metadata={"help": "path to fastBPE BPE"}) + + +@register_bpe("fastbpe", dataclass=fastBPEConfig) +class fastBPE(object): + def __init__(self, cfg): + if cfg.bpe_codes is None: + raise ValueError("--bpe-codes is required for --bpe=fastbpe") + codes = file_utils.cached_path(cfg.bpe_codes) + try: + import fastBPE + + self.bpe = fastBPE.fastBPE(codes) + self.bpe_symbol = "@@ " + except ImportError: + raise ImportError("Please install fastBPE with: pip install fastBPE") + + def encode(self, x: str) -> str: + return self.bpe.apply([x])[0] + + def decode(self, x: str) -> str: + return (x + " ").replace(self.bpe_symbol, "").rstrip() diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/gpt2_bpe.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/gpt2_bpe.py new file mode 100644 index 00000000..e661426a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/gpt2_bpe.py @@ -0,0 +1,45 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field + +from fairseq import file_utils +from fairseq.data.encoders import register_bpe +from fairseq.dataclass import FairseqDataclass + +from .gpt2_bpe_utils import get_encoder + + +DEFAULT_ENCODER_JSON = "https://dl.fbaipublicfiles.com/fairseq/gpt2_bpe/encoder.json" +DEFAULT_VOCAB_BPE = "https://dl.fbaipublicfiles.com/fairseq/gpt2_bpe/vocab.bpe" + + +@dataclass +class GPT2BPEConfig(FairseqDataclass): + gpt2_encoder_json: str = field( + default=DEFAULT_ENCODER_JSON, metadata={"help": "path to encoder.json"} + ) + gpt2_vocab_bpe: str = field( + default=DEFAULT_VOCAB_BPE, metadata={"help": "path to vocab.bpe"} + ) + + +@register_bpe("gpt2", dataclass=GPT2BPEConfig) +class GPT2BPE(object): + def __init__(self, cfg): + encoder_json = file_utils.cached_path(cfg.gpt2_encoder_json) + vocab_bpe = file_utils.cached_path(cfg.gpt2_vocab_bpe) + self.bpe = get_encoder(encoder_json, vocab_bpe) + + def encode(self, x: str) -> str: + return " ".join(map(str, self.bpe.encode(x))) + + def decode(self, x: str) -> str: + return self.bpe.decode( + [int(tok) if tok not in {"", ""} else tok for tok in x.split()] + ) + + def is_beginning_of_word(self, x: str) -> bool: + return self.decode(x).startswith(" ") diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/gpt2_bpe_utils.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/gpt2_bpe_utils.py new file mode 100644 index 00000000..996d3d4a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/gpt2_bpe_utils.py @@ -0,0 +1,140 @@ +""" +Byte pair encoding utilities from GPT-2. + +Original source: https://github.com/openai/gpt-2/blob/master/src/encoder.py +Original license: MIT +""" + +import json +from functools import lru_cache + + +@lru_cache() +def bytes_to_unicode(): + """ + Returns list of utf-8 byte and a corresponding list of unicode strings. + The reversible bpe codes work on unicode strings. + This means you need a large # of unicode characters in your vocab if you want to avoid UNKs. + When you're at something like a 10B token dataset you end up needing around 5K for decent coverage. + This is a signficant percentage of your normal, say, 32K bpe vocab. + To avoid that, we want lookup tables between utf-8 bytes and unicode strings. + And avoids mapping to whitespace/control characters the bpe code barfs on. + """ + bs = ( + list(range(ord("!"), ord("~") + 1)) + + list(range(ord("¡"), ord("¬") + 1)) + + list(range(ord("®"), ord("ÿ") + 1)) + ) + cs = bs[:] + n = 0 + for b in range(2**8): + if b not in bs: + bs.append(b) + cs.append(2**8 + n) + n += 1 + cs = [chr(n) for n in cs] + return dict(zip(bs, cs)) + + +def get_pairs(word): + """Return set of symbol pairs in a word. + Word is represented as tuple of symbols (symbols being variable-length strings). + """ + pairs = set() + prev_char = word[0] + for char in word[1:]: + pairs.add((prev_char, char)) + prev_char = char + return pairs + + +class Encoder: + def __init__(self, encoder, bpe_merges, errors="replace"): + self.encoder = encoder + self.decoder = {v: k for k, v in self.encoder.items()} + self.errors = errors # how to handle errors in decoding + self.byte_encoder = bytes_to_unicode() + self.byte_decoder = {v: k for k, v in self.byte_encoder.items()} + self.bpe_ranks = dict(zip(bpe_merges, range(len(bpe_merges)))) + self.cache = {} + + try: + import regex as re + + self.re = re + except ImportError: + raise ImportError("Please install regex with: pip install regex") + + # Should haved added re.IGNORECASE so BPE merges can happen for capitalized versions of contractions + self.pat = self.re.compile( + r"""'s|'t|'re|'ve|'m|'ll|'d| ?\p{L}+| ?\p{N}+| ?[^\s\p{L}\p{N}]+|\s+(?!\S)|\s+""" + ) + + def bpe(self, token): + if token in self.cache: + return self.cache[token] + word = tuple(token) + pairs = get_pairs(word) + + if not pairs: + return token + + while True: + bigram = min(pairs, key=lambda pair: self.bpe_ranks.get(pair, float("inf"))) + if bigram not in self.bpe_ranks: + break + first, second = bigram + new_word = [] + i = 0 + while i < len(word): + try: + j = word.index(first, i) + new_word.extend(word[i:j]) + i = j + except: + new_word.extend(word[i:]) + break + + if word[i] == first and i < len(word) - 1 and word[i + 1] == second: + new_word.append(first + second) + i += 2 + else: + new_word.append(word[i]) + i += 1 + new_word = tuple(new_word) + word = new_word + if len(word) == 1: + break + else: + pairs = get_pairs(word) + word = " ".join(word) + self.cache[token] = word + return word + + def encode(self, text): + bpe_tokens = [] + for token in self.re.findall(self.pat, text): + token = "".join(self.byte_encoder[b] for b in token.encode("utf-8")) + bpe_tokens.extend( + self.encoder[bpe_token] for bpe_token in self.bpe(token).split(" ") + ) + return bpe_tokens + + def decode(self, tokens): + text = "".join([self.decoder.get(token, token) for token in tokens]) + text = bytearray([self.byte_decoder[c] for c in text]).decode( + "utf-8", errors=self.errors + ) + return text + + +def get_encoder(encoder_json_path, vocab_bpe_path): + with open(encoder_json_path, "r") as f: + encoder = json.load(f) + with open(vocab_bpe_path, "r", encoding="utf-8") as f: + bpe_data = f.read() + bpe_merges = [tuple(merge_str.split()) for merge_str in bpe_data.split("\n")[1:-1]] + return Encoder( + encoder=encoder, + bpe_merges=bpe_merges, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/hf_bert_bpe.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/hf_bert_bpe.py new file mode 100644 index 00000000..a41c0593 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/hf_bert_bpe.py @@ -0,0 +1,50 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +from typing import Optional + +from fairseq.data.encoders import register_bpe +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class BertBPEConfig(FairseqDataclass): + bpe_cased: bool = field(default=False, metadata={"help": "set for cased BPE"}) + bpe_vocab_file: Optional[str] = field( + default=None, metadata={"help": "bpe vocab file"} + ) + + +@register_bpe("bert", dataclass=BertBPEConfig) +class BertBPE(object): + def __init__(self, cfg): + try: + from transformers import BertTokenizer + except ImportError: + raise ImportError( + "Please install transformers with: pip install transformers" + ) + + if cfg.bpe_vocab_file: + self.bert_tokenizer = BertTokenizer( + cfg.bpe_vocab_file, do_lower_case=not cfg.bpe_cased + ) + else: + vocab_file_name = ( + "bert-base-cased" if cfg.bpe_cased else "bert-base-uncased" + ) + self.bert_tokenizer = BertTokenizer.from_pretrained(vocab_file_name) + + def encode(self, x: str) -> str: + return " ".join(self.bert_tokenizer.tokenize(x)) + + def decode(self, x: str) -> str: + return self.bert_tokenizer.clean_up_tokenization( + self.bert_tokenizer.convert_tokens_to_string(x.split(" ")) + ) + + def is_beginning_of_word(self, x: str) -> bool: + return not x.startswith("##") diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/hf_byte_bpe.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/hf_byte_bpe.py new file mode 100644 index 00000000..c508578d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/hf_byte_bpe.py @@ -0,0 +1,50 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field + +from fairseq.data.encoders import register_bpe +from fairseq.dataclass import FairseqDataclass +from fairseq import file_utils + + +@dataclass +class HuggingFaceByteLevelBPEConfig(FairseqDataclass): + bpe_merges: str = field(default="???", metadata={"help": "path to merges.txt"}) + bpe_vocab: str = field(default="???", metadata={"help": "path to vocab.json"}) + bpe_add_prefix_space: bool = field( + default=False, metadata={"help": "add prefix space before encoding"} + ) + + +@register_bpe("hf_byte_bpe", dataclass=HuggingFaceByteLevelBPEConfig) +class HuggingFaceByteLevelBPE(object): + def __init__(self, cfg): + try: + from tokenizers import ByteLevelBPETokenizer + except ImportError: + raise ImportError( + "Please install huggingface/tokenizers with: " "pip install tokenizers" + ) + + bpe_vocab = file_utils.cached_path(cfg.bpe_vocab) + bpe_merges = file_utils.cached_path(cfg.bpe_merges) + + self.bpe = ByteLevelBPETokenizer( + bpe_vocab, + bpe_merges, + add_prefix_space=cfg.bpe_add_prefix_space, + ) + + def encode(self, x: str) -> str: + return " ".join(map(str, self.bpe.encode(x).ids)) + + def decode(self, x: str) -> str: + return self.bpe.decode( + [int(tok) if tok not in {"", ""} else tok for tok in x.split()] + ) + + def is_beginning_of_word(self, x: str) -> bool: + return self.decode(x).startswith(" ") diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/moses_tokenizer.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/moses_tokenizer.py new file mode 100644 index 00000000..e236dad1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/moses_tokenizer.py @@ -0,0 +1,49 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field + +from fairseq.data.encoders import register_tokenizer +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class MosesTokenizerConfig(FairseqDataclass): + source_lang: str = field(default="en", metadata={"help": "source language"}) + target_lang: str = field(default="en", metadata={"help": "target language"}) + moses_no_dash_splits: bool = field( + default=False, metadata={"help": "don't apply dash split rules"} + ) + moses_no_escape: bool = field( + default=False, + metadata={"help": "don't perform HTML escaping on apostrophe, quotes, etc."}, + ) + + +@register_tokenizer("moses", dataclass=MosesTokenizerConfig) +class MosesTokenizer(object): + def __init__(self, cfg: MosesTokenizerConfig): + self.cfg = cfg + + try: + from sacremoses import MosesTokenizer, MosesDetokenizer + + self.tok = MosesTokenizer(cfg.source_lang) + self.detok = MosesDetokenizer(cfg.target_lang) + except ImportError: + raise ImportError( + "Please install Moses tokenizer with: pip install sacremoses" + ) + + def encode(self, x: str) -> str: + return self.tok.tokenize( + x, + aggressive_dash_splits=(not self.cfg.moses_no_dash_splits), + return_str=True, + escape=(not self.cfg.moses_no_escape), + ) + + def decode(self, x: str) -> str: + return self.detok.detokenize(x.split()) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/nltk_tokenizer.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/nltk_tokenizer.py new file mode 100644 index 00000000..0ab92377 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/nltk_tokenizer.py @@ -0,0 +1,24 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.data.encoders import register_tokenizer +from fairseq.dataclass import FairseqDataclass + + +@register_tokenizer("nltk", dataclass=FairseqDataclass) +class NLTKTokenizer(object): + def __init__(self, *unused): + try: + from nltk.tokenize import word_tokenize + + self.word_tokenize = word_tokenize + except ImportError: + raise ImportError("Please install nltk with: pip install nltk") + + def encode(self, x: str) -> str: + return " ".join(self.word_tokenize(x)) + + def decode(self, x: str) -> str: + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/sentencepiece_bpe.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/sentencepiece_bpe.py new file mode 100644 index 00000000..0aa6cd76 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/sentencepiece_bpe.py @@ -0,0 +1,65 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +from typing import Optional + +from fairseq import file_utils +from fairseq.data.encoders import register_bpe +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class SentencepieceConfig(FairseqDataclass): + sentencepiece_model: str = field( + default="???", metadata={"help": "path to sentencepiece model"} + ) + sentencepiece_enable_sampling: bool = field( + default=False, metadata={"help": "enable sampling"} + ) + sentencepiece_alpha: Optional[float] = field( + default=None, + metadata={ + "help": "soothing parameter for unigram sampling, " + "and merge probability for BPE-dropout" + }, + ) + + +@register_bpe("sentencepiece", dataclass=SentencepieceConfig) +class SentencepieceBPE(object): + def __init__(self, cfg): + self.enable_sampling = cfg.sentencepiece_enable_sampling + self.alpha = cfg.sentencepiece_alpha + sentencepiece_model = file_utils.cached_path(cfg.sentencepiece_model) + try: + import sentencepiece as spm + + self.sp = spm.SentencePieceProcessor() + self.sp.Load(sentencepiece_model) + except ImportError: + raise ImportError( + "Please install sentencepiece with: pip install sentencepiece" + ) + + def encode(self, x: str) -> str: + return " ".join( + self.sp.Encode( + x, out_type=str, enable_sampling=self.enable_sampling, alpha=self.alpha + ) + ) + + def decode(self, x: str) -> str: + return x.replace(" ", "").replace("\u2581", " ").strip() + + def is_beginning_of_word(self, x: str) -> bool: + if x in ["", "", "", ""]: + # special elements are always considered beginnings + # HACK: this logic is already present in fairseq/tasks/masked_lm.py + # but these special tokens are also contained in the sentencepiece + # vocabulary which causes duplicate special tokens. This hack makes + # sure that they are all taken into account. + return True + return x.startswith("\u2581") diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/space_tokenizer.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/space_tokenizer.py new file mode 100644 index 00000000..925ad41b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/space_tokenizer.py @@ -0,0 +1,21 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import re + +from fairseq.data.encoders import register_tokenizer +from fairseq.dataclass import FairseqDataclass + + +@register_tokenizer("space", dataclass=FairseqDataclass) +class SpaceTokenizer(object): + def __init__(self, *unused): + self.space_tok = re.compile(r"\s+") + + def encode(self, x: str) -> str: + return self.space_tok.sub(" ", x) + + def decode(self, x: str) -> str: + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/subword_nmt_bpe.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/subword_nmt_bpe.py new file mode 100644 index 00000000..5d724d27 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/subword_nmt_bpe.py @@ -0,0 +1,54 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field + +from fairseq import file_utils +from fairseq.data.encoders import register_bpe +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class SubwordNMTBPEConfig(FairseqDataclass): + bpe_codes: str = field(default="???", metadata={"help": "path to subword NMT BPE"}) + bpe_separator: str = field(default="@@", metadata={"help": "BPE separator"}) + + +@register_bpe("subword_nmt", dataclass=SubwordNMTBPEConfig) +class SubwordNMTBPE(object): + def __init__(self, cfg): + if cfg.bpe_codes is None: + raise ValueError("--bpe-codes is required for --bpe=subword_nmt") + codes = file_utils.cached_path(cfg.bpe_codes) + try: + from subword_nmt import apply_bpe + + bpe_parser = apply_bpe.create_parser() + bpe_args = bpe_parser.parse_args( + [ + "--codes", + codes, + "--separator", + cfg.bpe_separator, + ] + ) + self.bpe = apply_bpe.BPE( + bpe_args.codes, + bpe_args.merges, + bpe_args.separator, + None, + bpe_args.glossaries, + ) + self.bpe_symbol = bpe_args.separator + " " + except ImportError: + raise ImportError( + "Please install subword_nmt with: pip install subword-nmt" + ) + + def encode(self, x: str) -> str: + return self.bpe.process_line(x) + + def decode(self, x: str) -> str: + return (x + " ").replace(self.bpe_symbol, "").rstrip() diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/encoders/utils.py b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/utils.py new file mode 100644 index 00000000..d93eb532 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/encoders/utils.py @@ -0,0 +1,30 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from fairseq.data import encoders + + +def get_whole_word_mask(args, dictionary): + bpe = encoders.build_bpe(args) + if bpe is not None: + + def is_beginning_of_word(i): + if i < dictionary.nspecial: + # special elements are always considered beginnings + return True + tok = dictionary[i] + if tok.startswith("madeupword"): + return True + try: + return bpe.is_beginning_of_word(tok) + except ValueError: + return True + + mask_whole_words = torch.ByteTensor( + list(map(is_beginning_of_word, range(len(dictionary)))) + ) + return mask_whole_words + return None diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/fairseq_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/fairseq_dataset.py new file mode 100644 index 00000000..2bde7fc5 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/fairseq_dataset.py @@ -0,0 +1,205 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import numpy as np +import torch.utils.data +from fairseq.data import data_utils + +logger = logging.getLogger(__name__) + + +class EpochListening: + """Mixin for receiving updates whenever the epoch increments.""" + + @property + def can_reuse_epoch_itr_across_epochs(self): + """ + Whether we can reuse the :class:`fairseq.data.EpochBatchIterator` for + this dataset across epochs. + + This needs to return ``False`` if the sample sizes can change across + epochs, in which case we may need to regenerate batches at each epoch. + If your dataset relies in ``set_epoch`` then you should consider setting + this to ``False``. + """ + return True + + def set_epoch(self, epoch): + """Will receive the updated epoch number at the beginning of the epoch.""" + pass + + +class FairseqDataset(torch.utils.data.Dataset, EpochListening): + """A dataset that provides helpers for batching.""" + + def __getitem__(self, index): + raise NotImplementedError + + def __len__(self): + raise NotImplementedError + + def collater(self, samples): + """Merge a list of samples to form a mini-batch. + + Args: + samples (List[dict]): samples to collate + + Returns: + dict: a mini-batch suitable for forwarding with a Model + """ + raise NotImplementedError + + def num_tokens(self, index): + """Return the number of tokens in a sample. This value is used to + enforce ``--max-tokens`` during batching.""" + raise NotImplementedError + + def num_tokens_vec(self, indices): + """Return the number of tokens for a set of positions defined by indices. + This value is used to enforce ``--max-tokens`` during batching.""" + raise NotImplementedError + + def size(self, index): + """Return an example's size as a float or tuple. This value is used when + filtering a dataset with ``--max-positions``.""" + raise NotImplementedError + + def ordered_indices(self): + """Return an ordered list of indices. Batches will be constructed based + on this order.""" + return np.arange(len(self), dtype=np.int64) + + @property + def supports_prefetch(self): + """Whether this dataset supports prefetching.""" + return False + + def attr(self, attr: str, index: int): + return getattr(self, attr, None) + + def prefetch(self, indices): + """Prefetch the data required for this epoch.""" + raise NotImplementedError + + def get_batch_shapes(self): + """ + Return a list of valid batch shapes, for example:: + + [(8, 512), (16, 256), (32, 128)] + + The first dimension of each tuple is the batch size and can be ``None`` + to automatically infer the max batch size based on ``--max-tokens``. + The second dimension of each tuple is the max supported length as given + by :func:`fairseq.data.FairseqDataset.num_tokens`. + + This will be used by :func:`fairseq.data.FairseqDataset.batch_by_size` + to restrict batch shapes. This is useful on TPUs to avoid too many + dynamic shapes (and recompilations). + """ + return None + + def batch_by_size( + self, + indices, + max_tokens=None, + max_sentences=None, + required_batch_size_multiple=1, + ): + """ + Given an ordered set of indices, return batches according to + *max_tokens*, *max_sentences* and *required_batch_size_multiple*. + """ + from fairseq.data import data_utils + + fixed_shapes = self.get_batch_shapes() + if fixed_shapes is not None: + + def adjust_bsz(bsz, num_tokens): + if bsz is None: + assert max_tokens is not None, "Must specify --max-tokens" + bsz = max_tokens // num_tokens + if max_sentences is not None: + bsz = min(bsz, max_sentences) + elif ( + bsz >= required_batch_size_multiple + and bsz % required_batch_size_multiple != 0 + ): + bsz -= bsz % required_batch_size_multiple + return bsz + + fixed_shapes = np.array( + [ + [adjust_bsz(bsz, num_tokens), num_tokens] + for (bsz, num_tokens) in fixed_shapes + ] + ) + + try: + num_tokens_vec = self.num_tokens_vec(indices).astype("int64") + except NotImplementedError: + num_tokens_vec = None + + return data_utils.batch_by_size( + indices, + num_tokens_fn=self.num_tokens, + num_tokens_vec=num_tokens_vec, + max_tokens=max_tokens, + max_sentences=max_sentences, + required_batch_size_multiple=required_batch_size_multiple, + fixed_shapes=fixed_shapes, + ) + + def filter_indices_by_size(self, indices, max_sizes): + """ + Filter a list of sample indices. Remove those that are longer than + specified in *max_sizes*. + + WARNING: don't update, override method in child classes + + Args: + indices (np.array): original array of sample indices + max_sizes (int or list[int] or tuple[int]): max sample size, + can be defined separately for src and tgt (then list or tuple) + + Returns: + np.array: filtered sample array + list: list of removed indices + """ + if isinstance(max_sizes, float) or isinstance(max_sizes, int): + if hasattr(self, "sizes") and isinstance(self.sizes, np.ndarray): + ignored = indices[self.sizes[indices] > max_sizes].tolist() + indices = indices[self.sizes[indices] <= max_sizes] + elif ( + hasattr(self, "sizes") + and isinstance(self.sizes, list) + and len(self.sizes) == 1 + ): + ignored = indices[self.sizes[0][indices] > max_sizes].tolist() + indices = indices[self.sizes[0][indices] <= max_sizes] + else: + indices, ignored = data_utils._filter_by_size_dynamic( + indices, self.size, max_sizes + ) + else: + indices, ignored = data_utils._filter_by_size_dynamic( + indices, self.size, max_sizes + ) + return indices, ignored + + @property + def supports_fetch_outside_dataloader(self): + """Whether this dataset supports fetching outside the workers of the dataloader.""" + return True + + +class FairseqIterableDataset(torch.utils.data.IterableDataset, EpochListening): + """ + For datasets that need to be read sequentially, usually because the data is + being streamed or otherwise can't be manipulated on a single machine. + """ + + def __iter__(self): + raise NotImplementedError diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/fasta_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/fasta_dataset.py new file mode 100644 index 00000000..00701197 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/fasta_dataset.py @@ -0,0 +1,107 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import os +import subprocess +import threading +from pathlib import Path + +import numpy as np +import torch + + +def fasta_file_path(prefix_path): + return prefix_path + ".fasta" + + +class FastaDataset(torch.utils.data.Dataset): + """ + For loading protein sequence datasets in the common FASTA data format + """ + + def __init__(self, path: str, cache_indices=False): + self.fn = fasta_file_path(path) + self.threadlocal = threading.local() + self.cache = Path(f"{path}.fasta.idx.npy") + if cache_indices: + if self.cache.exists(): + self.offsets, self.sizes = np.load(self.cache) + else: + self.offsets, self.sizes = self._build_index(path) + np.save(self.cache, np.stack([self.offsets, self.sizes])) + else: + self.offsets, self.sizes = self._build_index(path) + + def _get_file(self): + if not hasattr(self.threadlocal, "f"): + self.threadlocal.f = open(self.fn, "r") + return self.threadlocal.f + + def __getitem__(self, idx): + f = self._get_file() + f.seek(self.offsets[idx]) + desc = f.readline().strip() + line = f.readline() + seq = "" + while line != "" and line[0] != ">": + seq += line.strip() + line = f.readline() + return desc, seq + + def __len__(self): + return self.offsets.size + + def _build_index(self, path: str): + # Use grep and awk to get 100M/s on local SSD. + # Should process your enormous 100G fasta in ~10 min single core... + path = fasta_file_path(path) + bytes_offsets = subprocess.check_output( + f"cat {path} | tqdm --bytes --total $(wc -c < {path})" + "| grep --byte-offset '^>' -o | cut -d: -f1", + shell=True, + ) + fasta_lengths = subprocess.check_output( + f"cat {path} | tqdm --bytes --total $(wc -c < {path})" + "| awk '/^>/ {print \"\";next;} { printf(\"%s\",$0);}' | tail -n+2 | awk '{print length($1)}'", + shell=True, + ) + bytes_np = np.fromstring(bytes_offsets, dtype=np.int64, sep=" ") + sizes_np = np.fromstring(fasta_lengths, dtype=np.int64, sep=" ") + return bytes_np, sizes_np + + def __setstate__(self, state): + self.__dict__ = state + self.threadlocal = threading.local() + + def __getstate__(self): + d = {} + for i, v in self.__dict__.items(): + if i != "threadlocal": + d[i] = v + return d + + def __del__(self): + if hasattr(self.threadlocal, "f"): + self.threadlocal.f.close() + del self.threadlocal.f + + @staticmethod + def exists(path): + return os.path.exists(fasta_file_path(path)) + + +class EncodedFastaDataset(FastaDataset): + """ + The FastaDataset returns raw sequences - this allows us to return + indices with a dictionary instead. + """ + + def __init__(self, path, dictionary): + super().__init__(path, cache_indices=True) + self.dictionary = dictionary + + def __getitem__(self, idx): + desc, seq = super().__getitem__(idx) + return self.dictionary.encode_line(seq, line_tokenizer=list).long() diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/huffman/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/data/huffman/__init__.py new file mode 100644 index 00000000..9b61fafa --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/huffman/__init__.py @@ -0,0 +1,21 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .huffman_coder import HuffmanCodeBuilder, HuffmanCoder +from .huffman_mmap_indexed_dataset import ( + HuffmanMMapIndex, + HuffmanMMapIndexedDataset, + HuffmanMMapIndexedDatasetBuilder, + vocab_file_path, +) + +__all__ = [ + "HuffmanCoder", + "HuffmanCodeBuilder", + "HuffmanMMapIndexedDatasetBuilder", + "HuffmanMMapIndexedDataset", + "HuffmanMMapIndex", + "vocab_file_path", +] diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/huffman/huffman_coder.py b/PyTorch/NLP/new-Transformer/fairseq/data/huffman/huffman_coder.py new file mode 100644 index 00000000..c04f8456 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/huffman/huffman_coder.py @@ -0,0 +1,267 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import re +import typing as tp +from collections import Counter, deque +from dataclasses import dataclass + +from bitarray import bitarray, util +from fairseq.data import Dictionary + +# basically we have to write to addressable bytes for the memory mapped +# dataset loader. Sentences that get encoded to a length that is not a +# multiple of BLOCKSIZE (a byte) will be padded to fit. (see _pad in the coder) +BLOCKSIZE = 8 + + +class HuffmanCoder: + def __init__( + self, root: "HuffmanNode", bos="", pad="", eos="", unk="" + ): + self.root = root + self.table = root.code_table() + self.bos_word, self.unk_word, self.pad_word, self.eos_word = bos, unk, pad, eos + + def _pad(self, a: bitarray) -> bitarray: + """ + bitpadding, 1 then 0. + + If the array is already a multiple of blocksize, we add a full block. + """ + pad_len = BLOCKSIZE - (len(a) % BLOCKSIZE) - 1 + padding = bitarray("1" + "0" * pad_len) + return a + padding + + def _unpad(self, a: bitarray) -> bitarray: + """ + remove the bitpadding. + + There will be a set of 0s preceded by a 1 at the end of the bitarray, we remove that + """ + # count the 0 padding at the end until we find the first 1 + # we want to remove the one too + remove_cnt = util.rindex(a, 1) + return a[:remove_cnt] + + def encode(self, iter: tp.List[str]) -> bytes: + """ + encode a list of tokens a return bytes. We use bitpadding to make sure the encoded bits fit in bytes. + """ + a = bitarray() + for token in iter: + code = self.get_code(token) + if code is None: + if self.unk_word is None: + raise Exception(f"unknown token {token} cannot be encoded.") + else: + token = self.unk_word + a = a + self.get_code(token) + return self._pad(a).tobytes() + + def decode(self, bits: bytes) -> tp.Iterator["HuffmanNode"]: + """ + take bitpadded bytes and decode it to a set of leaves. You can then use each node to find the symbol/id + """ + a = bitarray() + a.frombytes(bits) + return self.root.decode(self._unpad(a)) + + def get_code(self, symbol: str) -> tp.Optional[bitarray]: + node = self.get_node(symbol) + return None if node is None else node.code + + def get_node(self, symbol: str) -> "HuffmanNode": + return self.table.get(symbol) + + @classmethod + def from_file( + cls, + filename: str, + bos="", + pad="", + eos="", + unk="", + ) -> "HuffmanCoder": + builder = HuffmanCodeBuilder.from_file(filename) + return builder.build_code(bos=bos, pad=pad, eos=eos, unk=unk) + + def to_file(self, filename, sep="\t"): + nodes = list(self.table.values()) + nodes.sort(key=lambda n: n.id) + with open(filename, "w", encoding="utf-8") as output: + for n in nodes: + output.write(f"{n.symbol}{sep}{n.count}\n") + + def __iter__(self): + for n in self.table.values(): + yield n + + def merge(self, other_coder: "HuffmanCoder") -> "HuffmanCoder": + builder = HuffmanCodeBuilder() + for n in self: + builder.increment(n.symbol, n.count) + for n in other_coder: + builder.increment(n.symbol, n.count) + return builder.build_code() + + def __eq__(self, other: "HuffmanCoder") -> bool: + return self.table == other.table + + def __len__(self) -> int: + return len(self.table) + + def __contains__(self, sym: str) -> bool: + return sym in self.table + + def to_dictionary(self) -> Dictionary: + dictionary = Dictionary(bos=self.bos, unk=self.unk, pad=self.pad, eos=self.eos) + for n in self: + dictionary.add_symbol(n.symbol, n=n.count) + dictionary.finalize() + return dictionary + + +@dataclass +class HuffmanNode: + """ + a node in a Huffman tree + """ + + id: int + count: int + symbol: tp.Optional[str] = None + left: tp.Optional["HuffmanNode"] = None + right: tp.Optional["HuffmanNode"] = None + code: tp.Optional[bitarray] = None + + def is_leaf(self) -> bool: + return self.left is None and self.right is None + + def code_table( + self, prefix: tp.Optional[bitarray] = None + ) -> tp.Dict[str, "HuffmanNode"]: + defaulted_prefix = prefix if prefix is not None else bitarray() + if self.is_leaf(): + self.code = ( + defaulted_prefix if len(defaulted_prefix) > 0 else bitarray("0") + ) # leaf could be the root if there is only one symbol + return {self.symbol: self} + + codes_right = self.right.code_table(defaulted_prefix + bitarray([0])) + codes_left = self.left.code_table(defaulted_prefix + bitarray([1])) + return {**codes_left, **codes_right} + + def decode(self, bits: bitarray) -> tp.Iterator["HuffmanNode"]: + current_node = self + for bit in bits: + if bit == 0: # go right + current_node = current_node.right + else: # go left + current_node = current_node.left + if current_node is None: + # we shouldn't be on a leaf here + raise Exception("fell off a leaf") + if current_node.is_leaf(): + yield current_node + current_node = self + if current_node != self: + raise Exception("couldn't decode all the bits") + + +class HuffmanCodeBuilder: + """ + build a dictionary with occurence count and then build the Huffman code for it. + """ + + def __init__(self): + self.symbols = Counter() + + def add_symbols(self, *syms) -> None: + self.symbols.update(syms) + + def increment(self, symbol: str, cnt: int) -> None: + self.symbols[symbol] += cnt + + @classmethod + def from_file(cls, filename): + c = cls() + with open(filename, "r", encoding="utf-8") as input: + for line in input: + split = re.split(r"[\s]+", line) + c.increment(split[0], int(split[1])) + return c + + def to_file(self, filename, sep="\t"): + with open(filename, "w", encoding="utf-8") as output: + for (tok, cnt) in self.symbols.most_common(): + output.write(f"{tok}{sep}{cnt}\n") + + def _smallest(self, q1: deque, q2: deque) -> HuffmanNode: + if len(q1) == 0: + return q2.pop() + + if len(q2) == 0: + return q1.pop() + + if q1[-1].count < q2[-1].count: + return q1.pop() + + return q2.pop() + + def __add__(self, c: "HuffmanCodeBuilder") -> "HuffmanCodeBuilder": + new_c = self.symbols + c.symbols + new_b = HuffmanCodeBuilder() + new_b.symbols = new_c + return new_b + + def build_code( + self, + bos="", + pad="", + eos="", + unk="", + ) -> HuffmanCoder: + assert len(self.symbols) > 0, "cannot build code from empty list of symbols" + + if self.symbols[bos] == 0: + self.add_symbols(bos) + if self.symbols[pad] == 0: + self.add_symbols(pad) + if self.symbols[eos] == 0: + self.add_symbols(eos) + if self.symbols[unk] == 0: + self.add_symbols(unk) + + node_id = 0 + leaves_queue = deque( + [ + HuffmanNode(symbol=symbol, count=count, id=idx) + for idx, (symbol, count) in enumerate(self.symbols.most_common()) + ] + ) # left are the most common, right are the least common + + if len(leaves_queue) == 1: + root = leaves_queue.pop() + root.id = 0 + return HuffmanCoder(root) + + nodes_queue = deque() + + while len(leaves_queue) > 0 or len(nodes_queue) != 1: + # get the lowest two nodes at the head of each queue + node1 = self._smallest(leaves_queue, nodes_queue) + node2 = self._smallest(leaves_queue, nodes_queue) + + # add new node + nodes_queue.appendleft( + HuffmanNode( + count=node1.count + node2.count, left=node1, right=node2, id=node_id + ) + ) + node_id += 1 + + # we are left with the root + return HuffmanCoder(nodes_queue.pop(), bos=bos, pad=pad, eos=eos, unk=unk) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/huffman/huffman_mmap_indexed_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/huffman/huffman_mmap_indexed_dataset.py new file mode 100644 index 00000000..9b098f2c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/huffman/huffman_mmap_indexed_dataset.py @@ -0,0 +1,287 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import mmap +import os +import shutil +import struct +import typing as tp +from functools import lru_cache + +import numpy as np +import torch +from fairseq.data import indexed_dataset +from fairseq.data.huffman import HuffmanCoder +from fairseq.file_io import PathManager + + +class HuffmanMMapIndex: + """ + keep an index of the offsets in the huffman binary file. + First a header, then the list of sizes (num tokens) for each instance and finally + the addresses of each instance. + """ + + _HDR_MAGIC = b"HUFFIDX\x00\x00" + _VERSION = 1 + + @classmethod + def writer(cls, path: str, data_len: int): + class _Writer: + def __enter__(self): + self._file = open(path, "wb") + + # write header (magic + version) + self._file.write(cls._HDR_MAGIC) + self._file.write(struct.pack(" None: + self._path_prefix = path_prefix + self._coder = coder + self._sizes = [] + self._ptrs = [] + self._data_len = 0 + + def open(self): + self._coder.to_file(vocab_file_path(self._path_prefix)) + self._data_file = open(indexed_dataset.data_file_path(self._path_prefix), "wb") + + def __enter__(self) -> "HuffmanMMapIndexedDatasetBuilder": + self.open() + return self + + def add_item(self, tokens: tp.List[str]) -> None: + """ + add a list of tokens to the dataset, they will compressed with the + provided coder before being written to file. + """ + encoded = self._coder.encode(tokens) + code_len = len(encoded) + last_ptr = 0 + if len(self._ptrs) > 0: + last_ptr = self._ptrs[-1] + self._sizes.append(len(tokens)) + self._ptrs.append(last_ptr + code_len) + self._data_len += code_len + self._data_file.write(encoded) + + def append(self, other_dataset_path_prefix: str) -> None: + """ + append an existing dataset. + Beware, if it wasn't built with the same coder, you are in trouble. + """ + other_index = HuffmanMMapIndex( + indexed_dataset.index_file_path(other_dataset_path_prefix) + ) + for (ptr, size) in other_index: + self._ptrs.append(ptr + self._data_len) + self._sizes.append(size) + + # Concatenate data + with open(indexed_dataset.data_file_path(other_dataset_path_prefix), "rb") as f: + shutil.copyfileobj(f, self._data_file) + + self._data_len += other_index.data_len + + def close(self): + self._data_file.close() + with HuffmanMMapIndex.writer( + indexed_dataset.index_file_path(self._path_prefix), self._data_len + ) as index: + index.write(self._sizes, self._ptrs) + + def __exit__(self, exc_type, exc_val, exc_tb) -> None: + self.close() diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/id_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/id_dataset.py new file mode 100644 index 00000000..3e4d7969 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/id_dataset.py @@ -0,0 +1,19 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +from . import FairseqDataset + + +class IdDataset(FairseqDataset): + def __getitem__(self, index): + return index + + def __len__(self): + return 0 + + def collater(self, samples): + return torch.tensor(samples) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/indexed_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/indexed_dataset.py new file mode 100644 index 00000000..81cba4af --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/indexed_dataset.py @@ -0,0 +1,587 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import shutil +import struct +from functools import lru_cache + +import numpy as np +import torch +from fairseq.dataclass.constants import DATASET_IMPL_CHOICES +from fairseq.data.fasta_dataset import FastaDataset +from fairseq.file_io import PathManager +from fairseq.data.huffman import HuffmanMMapIndexedDataset, HuffmanMMapIndex + +from . import FairseqDataset + +from typing import Union + + +def best_fitting_int_dtype( + max_int_to_represent, +) -> Union[np.uint16, np.uint32, np.int64]: + + if max_int_to_represent is None: + return np.uint32 # Safe guess + elif max_int_to_represent < 65500: + return np.uint16 + elif max_int_to_represent < 4294967295: + return np.uint32 + else: + return np.int64 + # we avoid np.uint64 because it doesn't save space and its type promotion behaves unexpectedly + # https://github.com/numpy/numpy/issues/5745 + + +def get_available_dataset_impl(): + return list(map(str, DATASET_IMPL_CHOICES)) + + +def infer_dataset_impl(path): + if IndexedRawTextDataset.exists(path): + return "raw" + elif IndexedDataset.exists(path): + with open(index_file_path(path), "rb") as f: + magic = f.read(8) + if magic == IndexedDataset._HDR_MAGIC: + return "cached" + elif magic == MMapIndexedDataset.Index._HDR_MAGIC[:8]: + return "mmap" + elif magic == HuffmanMMapIndex._HDR_MAGIC[:8]: + return "huffman" + else: + return None + elif FastaDataset.exists(path): + return "fasta" + else: + return None + + +def make_builder(out_file, impl, vocab_size=None): + if impl == "mmap": + return MMapIndexedDatasetBuilder( + out_file, dtype=best_fitting_int_dtype(vocab_size) + ) + elif impl == "fasta": + raise NotImplementedError + elif impl == "huffman": + raise ValueError( + "Use HuffmanCodeBuilder directly as it has a different interface." + ) + else: + return IndexedDatasetBuilder(out_file) + + +def make_dataset(path, impl, fix_lua_indexing=False, dictionary=None): + if impl == "raw" and IndexedRawTextDataset.exists(path): + assert dictionary is not None + return IndexedRawTextDataset(path, dictionary) + elif impl == "lazy" and IndexedDataset.exists(path): + return IndexedDataset(path, fix_lua_indexing=fix_lua_indexing) + elif impl == "cached" and IndexedDataset.exists(path): + return IndexedCachedDataset(path, fix_lua_indexing=fix_lua_indexing) + elif impl == "mmap" and MMapIndexedDataset.exists(path): + return MMapIndexedDataset(path) + elif impl == "fasta" and FastaDataset.exists(path): + from fairseq.data.fasta_dataset import EncodedFastaDataset + + return EncodedFastaDataset(path, dictionary) + elif impl == "huffman" and HuffmanMMapIndexedDataset.exists(path): + return HuffmanMMapIndexedDataset(path) + return None + + +def dataset_exists(path, impl): + if impl == "raw": + return IndexedRawTextDataset.exists(path) + elif impl == "mmap": + return MMapIndexedDataset.exists(path) + elif impl == "huffman": + return HuffmanMMapIndexedDataset.exists(path) + else: + return IndexedDataset.exists(path) + + +def read_longs(f, n): + a = np.empty(n, dtype=np.int64) + f.readinto(a) + return a + + +def write_longs(f, a): + f.write(np.array(a, dtype=np.int64)) + + +_code_to_dtype = { + 1: np.uint8, + 2: np.int8, + 3: np.int16, + 4: np.int32, + 5: np.int64, + 6: np.float64, + 7: np.double, + 8: np.uint16, + 9: np.uint32, + 10: np.uint64, +} + + +def _dtype_header_code(dtype) -> int: + for k in _code_to_dtype.keys(): + if _code_to_dtype[k] == dtype: + return k + raise ValueError(dtype) + + +def index_file_path(prefix_path): + return prefix_path + ".idx" + + +def data_file_path(prefix_path): + return prefix_path + ".bin" + + +class IndexedDataset(FairseqDataset): + """Loader for TorchNet IndexedDataset""" + + _HDR_MAGIC = b"TNTIDX\x00\x00" + + def __init__(self, path, fix_lua_indexing=False): + super().__init__() + self.path = path + self.fix_lua_indexing = fix_lua_indexing + self.data_file = None + self.read_index(path) + + def read_index(self, path): + with open(index_file_path(path), "rb") as f: + magic = f.read(8) + assert magic == self._HDR_MAGIC, ( + "Index file doesn't match expected format. " + "Make sure that --dataset-impl is configured properly." + ) + version = f.read(8) + assert struct.unpack("= self._len: + raise IndexError("index out of range") + + def __del__(self): + if self.data_file: + self.data_file.close() + + @lru_cache(maxsize=8) + def __getitem__(self, i) -> torch.Tensor: + if not self.data_file: + self.read_data(self.path) + self.check_index(i) + tensor_size = self.sizes[self.dim_offsets[i] : self.dim_offsets[i + 1]] + a = np.empty(tensor_size, dtype=self.dtype) + self.data_file.seek(self.data_offsets[i] * self.element_size) + self.data_file.readinto(a) + item = torch.from_numpy(a).long() + if self.fix_lua_indexing: + item -= 1 # subtract 1 for 0-based indexing + return item + + def __len__(self): + return self._len + + def num_tokens(self, index): + return self.sizes[index] + + def size(self, index): + return self.sizes[index] + + @staticmethod + def exists(path): + return PathManager.exists(index_file_path(path)) and PathManager.exists( + data_file_path(path) + ) + + @property + def supports_prefetch(self): + return False # avoid prefetching to save memory + + +class IndexedCachedDataset(IndexedDataset): + def __init__(self, path, fix_lua_indexing=False): + super().__init__(path, fix_lua_indexing=fix_lua_indexing) + self.cache = None + self.cache_index = {} + + @property + def supports_prefetch(self): + return True + + def prefetch(self, indices): + if all(i in self.cache_index for i in indices): + return + if not self.data_file: + self.read_data(self.path) + indices = sorted(set(indices)) + total_size = 0 + for i in indices: + total_size += self.data_offsets[i + 1] - self.data_offsets[i] + self.cache = np.empty(total_size, dtype=self.dtype) + ptx = 0 + self.cache_index.clear() + for i in indices: + self.cache_index[i] = ptx + size = self.data_offsets[i + 1] - self.data_offsets[i] + a = self.cache[ptx : ptx + size] + self.data_file.seek(self.data_offsets[i] * self.element_size) + self.data_file.readinto(a) + ptx += size + if self.data_file: + # close and delete data file after prefetch so we can pickle + self.data_file.close() + self.data_file = None + + @lru_cache(maxsize=8) + def __getitem__(self, i): + self.check_index(i) + tensor_size = self.sizes[self.dim_offsets[i] : self.dim_offsets[i + 1]] + a = np.empty(tensor_size, dtype=self.dtype) + ptx = self.cache_index[i] + np.copyto(a, self.cache[ptx : ptx + a.size]) + item = torch.from_numpy(a).long() + if self.fix_lua_indexing: + item -= 1 # subtract 1 for 0-based indexing + return item + + +class IndexedRawTextDataset(FairseqDataset): + """Takes a text file as input and binarizes it in memory at instantiation. + Original lines are also kept in memory""" + + def __init__(self, path, dictionary, append_eos=True, reverse_order=False): + self.tokens_list = [] + self.lines = [] + self.sizes = [] + self.append_eos = append_eos + self.reverse_order = reverse_order + self.read_data(path, dictionary) + self.size = len(self.tokens_list) + + def read_data(self, path, dictionary): + with open(path, "r", encoding="utf-8") as f: + for line in f: + self.lines.append(line.strip("\n")) + tokens = dictionary.encode_line( + line, + add_if_not_exist=False, + append_eos=self.append_eos, + reverse_order=self.reverse_order, + ).long() + self.tokens_list.append(tokens) + self.sizes.append(len(tokens)) + self.sizes = np.array(self.sizes) + + def check_index(self, i): + if i < 0 or i >= self.size: + raise IndexError("index out of range") + + @lru_cache(maxsize=8) + def __getitem__(self, i): + self.check_index(i) + return self.tokens_list[i] + + def get_original_text(self, i): + self.check_index(i) + return self.lines[i] + + def __del__(self): + pass + + def __len__(self): + return self.size + + def num_tokens(self, index): + return self.sizes[index] + + def size(self, index): + return self.sizes[index] + + @staticmethod + def exists(path): + return PathManager.exists(path) + + +class IndexedDatasetBuilder: + element_sizes = { + np.uint8: 1, + np.int8: 1, + np.int16: 2, + np.int32: 4, + np.int64: 8, + np.float64: 4, + np.double: 8, + } + + def __init__(self, out_file, dtype=np.int32): + self.out_file = open(out_file, "wb") + self.dtype = dtype + self.data_offsets = [0] + self.dim_offsets = [0] + self.sizes = [] + self.element_size = self.element_sizes[self.dtype] + + def add_item(self, tensor): + # +1 for Lua compatibility + bytes = self.out_file.write(np.array(tensor.numpy() + 1, dtype=self.dtype)) + self.data_offsets.append(self.data_offsets[-1] + bytes / self.element_size) + for s in tensor.size(): + self.sizes.append(s) + self.dim_offsets.append(self.dim_offsets[-1] + len(tensor.size())) + + def merge_file_(self, another_file): + index = IndexedDataset(another_file) + assert index.dtype == self.dtype + + begin = self.data_offsets[-1] + for offset in index.data_offsets[1:]: + self.data_offsets.append(begin + offset) + self.sizes.extend(index.sizes) + begin = self.dim_offsets[-1] + for dim_offset in index.dim_offsets[1:]: + self.dim_offsets.append(begin + dim_offset) + + with open(data_file_path(another_file), "rb") as f: + while True: + data = f.read(1024) + if data: + self.out_file.write(data) + else: + break + + def finalize(self, index_file): + self.out_file.close() + index = open(index_file, "wb") + index.write(b"TNTIDX\x00\x00") + index.write(struct.pack(" str: + local_index_path = PathManager.get_local_path(index_file_path(path)) + local_data_path = PathManager.get_local_path(data_file_path(path)) + + assert local_index_path.endswith(".idx") and local_data_path.endswith(".bin"), ( + "PathManager.get_local_path does not return files with expected patterns: " + f"{local_index_path} and {local_data_path}" + ) + + local_path = local_data_path[:-4] # stripping surfix ".bin" + assert local_path == local_index_path[:-4] # stripping surfix ".idx" + return local_path + + +class MMapIndexedDatasetBuilder: + def __init__(self, out_file, dtype=np.int64): + self._data_file = open(out_file, "wb") + self._dtype = dtype + self._sizes = [] + + def add_item(self, tensor): + np_array = np.array(tensor.numpy(), dtype=self._dtype) + self._data_file.write(np_array.tobytes(order="C")) + self._sizes.append(np_array.size) + + def merge_file_(self, another_file): + # Concatenate index + index = MMapIndexedDataset.Index(index_file_path(another_file)) + assert index.dtype == self._dtype + + for size in index.sizes: + self._sizes.append(size) + + # Concatenate data + with open(data_file_path(another_file), "rb") as f: + shutil.copyfileobj(f, self._data_file) + + def finalize(self, index_file): + self._data_file.close() + + with MMapIndexedDataset.Index.writer(index_file, self._dtype) as index: + index.write(self._sizes) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/iterators.py b/PyTorch/NLP/new-Transformer/fairseq/data/iterators.py new file mode 100644 index 00000000..beb681fc --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/iterators.py @@ -0,0 +1,821 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import itertools +import logging +import math +import operator +import os +import queue +import time +from threading import Thread + +import numpy as np +import torch +from fairseq.data import data_utils + + +logger = logging.getLogger(__name__) + +# Object used by _background_consumer to signal the source is exhausted +# to the main thread. +_sentinel = object() + + +class CountingIterator(object): + """Wrapper around an iterable that maintains the iteration count. + + Args: + iterable (iterable): iterable to wrap + start (int): starting iteration count. Note that this doesn't + actually advance the iterator. + total (int): override the iterator length returned by ``__len``. + This can be used to truncate *iterator*. + + Attributes: + n (int): number of elements consumed from this iterator + """ + + def __init__(self, iterable, start=None, total=None): + self._itr = iter(iterable) + self.n = start or getattr(iterable, "n", 0) + self.total = total if total is not None else self.n + len(iterable) + + def __len__(self): + return self.total + + def __iter__(self): + return self + + def __next__(self): + if not self.has_next(): + raise StopIteration + try: + x = next(self._itr) + except StopIteration: + raise IndexError( + f"Iterator expected to have length {self.total}, " + f"but exhausted at position {self.n}." + ) + self.n += 1 + return x + + def has_next(self): + """Whether the iterator has been exhausted.""" + return self.n < self.total + + def skip(self, n): + """Fast-forward the iterator by skipping n elements.""" + for _ in range(n): + next(self) + return self + + def take(self, n): + """Truncate the iterator to n elements at most.""" + self.total = min(self.total, n) + # Propagate this change to the underlying iterator + if hasattr(self._itr, "take"): + self._itr.take(max(n - self.n, 0)) + return self + + +class EpochBatchIterating(object): + def __len__(self) -> int: + raise NotImplementedError + + @property + def next_epoch_idx(self): + raise NotImplementedError + + def next_epoch_itr( + self, shuffle=True, fix_batches_to_gpus=False, set_dataset_epoch=True + ): + """Return a new iterator over the dataset. + + Args: + shuffle (bool, optional): shuffle batches before returning the + iterator (default: True). + fix_batches_to_gpus (bool, optional): ensure that batches are always + allocated to the same shards across epochs. Requires + that :attr:`dataset` supports prefetching (default: False). + set_dataset_epoch (bool, optional): update the wrapped Dataset with + the new epoch number (default: True). + """ + raise NotImplementedError + + def end_of_epoch(self) -> bool: + """Returns whether the most recent epoch iterator has been exhausted""" + raise NotImplementedError + + @property + def iterations_in_epoch(self) -> int: + """The number of consumed batches in the current epoch.""" + raise NotImplementedError + + def state_dict(self): + """Returns a dictionary containing a whole state of the iterator.""" + raise NotImplementedError + + def load_state_dict(self, state_dict): + """Copies the state of the iterator from the given *state_dict*.""" + raise NotImplementedError + + @property + def first_batch(self): + return "DUMMY" + + +class StreamingEpochBatchIterator(EpochBatchIterating): + """A steaming-style iterator over a :class:`torch.utils.data.IterableDataset`. + + Args: + dataset (~torch.utils.data.Dataset): dataset from which to load the data + max_sentences: batch size + collate_fn (callable): merges a list of samples to form a mini-batch + num_workers (int, optional): how many subprocesses to use for data + loading. 0 means the data will be loaded in the main process + (default: 0). + epoch (int, optional): the epoch to start the iterator from + (default: 1). + buffer_size (int, optional): the number of batches to keep ready in the + queue. Helps speeding up dataloading. When buffer_size is zero, the + default torch.utils.data.DataLoader preloading is used. + timeout (int, optional): if positive, the timeout value for collecting a batch + from workers. Should always be non-negative (default: ``0``). + """ + + def __init__( + self, + dataset, + max_sentences=1, + collate_fn=None, + epoch=1, + num_workers=0, + buffer_size=0, + timeout=0, + ): + assert isinstance(dataset, torch.utils.data.IterableDataset) + self.dataset = dataset + self.max_sentences = max_sentences + self.collate_fn = collate_fn + self.epoch = max(epoch, 1) # we use 1-based indexing for epochs + self.num_workers = num_workers + # This upper limit here is to prevent people from abusing this feature + # in a shared computing environment. + self.buffer_size = min(buffer_size, 20) + self.timeout = timeout + + self._current_epoch_iterator = None + + @property + def next_epoch_idx(self): + """Return the epoch index after *next_epoch_itr* is called.""" + if self._current_epoch_iterator is not None and self.end_of_epoch(): + return self.epoch + 1 + else: + return self.epoch + + def next_epoch_itr( + self, shuffle=True, fix_batches_to_gpus=False, set_dataset_epoch=True + ): + self.epoch = self.next_epoch_idx + if set_dataset_epoch and hasattr(self.dataset, "set_epoch"): + self.dataset.set_epoch(self.epoch) + self._current_epoch_iterator = self._get_iterator_for_epoch(self.epoch, shuffle) + return self._current_epoch_iterator + + def end_of_epoch(self) -> bool: + return not self._current_epoch_iterator.has_next() + + @property + def iterations_in_epoch(self) -> int: + if self._current_epoch_iterator is not None: + return self._current_epoch_iterator.n + return 0 + + def state_dict(self): + return { + "epoch": self.epoch, + } + + def load_state_dict(self, state_dict): + self.epoch = state_dict["epoch"] + + def _get_iterator_for_epoch(self, epoch, shuffle, offset=0): + if self.num_workers > 0: + os.environ["PYTHONWARNINGS"] = "ignore:semaphore_tracker:UserWarning" + + # Create data loader + worker_init_fn = getattr(self.dataset, "worker_init_fn", None) + itr = torch.utils.data.DataLoader( + self.dataset, + batch_size=self.max_sentences, + collate_fn=self.collate_fn, + num_workers=self.num_workers, + timeout=self.timeout, + worker_init_fn=worker_init_fn, + pin_memory=True, + ) + + # Wrap with a BufferedIterator if needed + if self.buffer_size > 0: + itr = BufferedIterator(self.buffer_size, itr) + + # Wrap with CountingIterator + itr = CountingIterator(itr, start=offset) + + return itr + + +class EpochBatchIterator(EpochBatchIterating): + """A multi-epoch iterator over a :class:`torch.utils.data.Dataset`. + + Compared to :class:`torch.utils.data.DataLoader`, this iterator: + + - can be reused across multiple epochs with the :func:`next_epoch_itr` + method (optionally shuffled between epochs) + - can be serialized/deserialized with the :func:`state_dict` and + :func:`load_state_dict` methods + - supports sharding with the *num_shards* and *shard_id* arguments + + Args: + dataset (~torch.utils.data.Dataset): dataset from which to load the data + collate_fn (callable): merges a list of samples to form a mini-batch + batch_sampler (~torch.utils.data.Sampler or a callable): an iterator over batches of + indices, or a callable to create such an iterator (~torch.utils.data.Sampler). + A callable batch_sampler will be called for each epoch to enable per epoch dynamic + batch iterators defined by this callable batch_sampler. + seed (int, optional): seed for random number generator for + reproducibility (default: 1). + num_shards (int, optional): shard the data iterator into N + shards (default: 1). + shard_id (int, optional): which shard of the data iterator to + return (default: 0). + num_workers (int, optional): how many subprocesses to use for data + loading. 0 means the data will be loaded in the main process + (default: 0). + epoch (int, optional): the epoch to start the iterator from + (default: 1). + buffer_size (int, optional): the number of batches to keep ready in the + queue. Helps speeding up dataloading. When buffer_size is zero, the + default torch.utils.data.DataLoader preloading is used. + timeout (int, optional): if positive, the timeout value for collecting a batch + from workers. Should always be non-negative (default: ``0``). + disable_shuffling (bool, optional): force disable shuffling + (default: ``False``). + skip_remainder_batch (bool, optional): if set, discard the last batch in an epoch + for the sake of training stability, as the last batch is usually smaller than + local_batch_size * distributed_word_size (default: ``False``). + grouped_shuffling (bool, optional): enable shuffling batches in groups + of num_shards. Ensures that each GPU receives similar length sequences when + batches are sorted by length. + """ + + def __init__( + self, + dataset, + collate_fn, + batch_sampler, + seed=1, + num_shards=1, + shard_id=0, + num_workers=0, + epoch=1, + buffer_size=0, + timeout=0, + disable_shuffling=False, + skip_remainder_batch=False, + grouped_shuffling=False, + ): + assert isinstance(dataset, torch.utils.data.Dataset) + self.dataset = dataset + self.collate_fn = collate_fn + self.batch_sampler = batch_sampler + self._frozen_batches = ( + tuple(batch_sampler) if not callable(batch_sampler) else None + ) + self.seed = seed + self.num_shards = num_shards + self.shard_id = shard_id + self.num_workers = num_workers + # This upper limit here is to prevent people from abusing this feature + # in a shared computing environment. + self.buffer_size = min(buffer_size, 20) + self.timeout = timeout + self.disable_shuffling = disable_shuffling + self.skip_remainder_batch = skip_remainder_batch + self.grouped_shuffling = grouped_shuffling + + self.epoch = max(epoch, 1) # we use 1-based indexing for epochs + self.shuffle = not disable_shuffling + self._cur_epoch_itr = None + self._next_epoch_itr = None + self._supports_prefetch = getattr(dataset, "supports_prefetch", False) + + @property + def frozen_batches(self): + if self._frozen_batches is None: + self._frozen_batches = tuple(self.batch_sampler(self.dataset, self.epoch)) + return self._frozen_batches + + @property + def first_batch(self): + if len(self.frozen_batches) == 0: + raise Exception( + "The dataset is empty. This could indicate " + "that all elements in the dataset have been skipped. " + "Try increasing the max number of allowed tokens or using " + "a larger dataset." + ) + + if getattr(self.dataset, "supports_fetch_outside_dataloader", True): + return self.collate_fn([self.dataset[i] for i in self.frozen_batches[0]]) + else: + return "DUMMY" + + def __len__(self): + return int(math.ceil(len(self.frozen_batches) / float(self.num_shards))) + + @property + def n(self): + return self.iterations_in_epoch + + @property + def next_epoch_idx(self): + """Return the epoch index after *next_epoch_itr* is called.""" + if self._next_epoch_itr is not None: + return self.epoch + elif self._cur_epoch_itr is not None and self.end_of_epoch(): + return self.epoch + 1 + else: + return self.epoch + + def next_epoch_itr( + self, shuffle=True, fix_batches_to_gpus=False, set_dataset_epoch=True + ): + """Return a new iterator over the dataset. + + Args: + shuffle (bool, optional): shuffle batches before returning the + iterator (default: True). + fix_batches_to_gpus (bool, optional): ensure that batches are always + allocated to the same shards across epochs. Requires + that :attr:`dataset` supports prefetching (default: False). + set_dataset_epoch (bool, optional): update the wrapped Dataset with + the new epoch number (default: True). + """ + if self.disable_shuffling: + shuffle = False + prev_epoch = self.epoch + self.epoch = self.next_epoch_idx + if set_dataset_epoch and hasattr(self.dataset, "set_epoch"): + self.dataset.set_epoch(self.epoch) + if self._next_epoch_itr is not None: + self._cur_epoch_itr = self._next_epoch_itr + self._next_epoch_itr = None + else: + if callable(self.batch_sampler) and prev_epoch != self.epoch: + # reset _frozen_batches to refresh the next epoch + self._frozen_batches = None + self._cur_epoch_itr = self._get_iterator_for_epoch( + self.epoch, + shuffle, + fix_batches_to_gpus=fix_batches_to_gpus, + ) + self.shuffle = shuffle + return self._cur_epoch_itr + + def end_of_epoch(self) -> bool: + """Returns whether the most recent epoch iterator has been exhausted""" + return not self._cur_epoch_itr.has_next() + + @property + def iterations_in_epoch(self): + """The number of consumed batches in the current epoch.""" + if self._cur_epoch_itr is not None: + return self._cur_epoch_itr.n + elif self._next_epoch_itr is not None: + return self._next_epoch_itr.n + return 0 + + def state_dict(self): + """Returns a dictionary containing a whole state of the iterator.""" + if self.end_of_epoch(): + epoch = self.epoch + 1 + iter_in_epoch = 0 + else: + epoch = self.epoch + iter_in_epoch = self.iterations_in_epoch + return { + "version": 2, + "epoch": epoch, + "iterations_in_epoch": iter_in_epoch, + "shuffle": self.shuffle, + } + + def load_state_dict(self, state_dict): + """Copies the state of the iterator from the given *state_dict*.""" + self.epoch = state_dict["epoch"] + itr_pos = state_dict.get("iterations_in_epoch", 0) + version = state_dict.get("version", 1) + if itr_pos > 0: + # fast-forward epoch iterator + self._next_epoch_itr = self._get_iterator_for_epoch( + self.epoch, + shuffle=state_dict.get("shuffle", True), + offset=itr_pos, + ) + if self._next_epoch_itr is None: + if version == 1: + # legacy behavior: we finished the epoch, increment epoch counter + self.epoch += 1 + else: + raise RuntimeError( + "Cannot resume training due to dataloader mismatch, please " + "report this to the fairseq developers. You can relaunch " + "training with `--reset-dataloader` and it should work." + ) + else: + self._next_epoch_itr = None + + def _get_iterator_for_epoch( + self, epoch, shuffle, fix_batches_to_gpus=False, offset=0 + ): + def shuffle_batches(batches, seed): + with data_utils.numpy_seed(seed): + + if self.grouped_shuffling: + grouped_batches = [ + batches[(i * self.num_shards) : ((i + 1) * self.num_shards)] + for i in range((len(batches) // self.num_shards)) + ] + np.random.shuffle(grouped_batches) + batches = list(itertools.chain(*grouped_batches)) + else: + np.random.shuffle(batches) + + return batches + + if self._supports_prefetch: + batches = self.frozen_batches + + if shuffle and not fix_batches_to_gpus: + batches = shuffle_batches(list(batches), self.seed + epoch) + + batches = list( + ShardedIterator(batches, self.num_shards, self.shard_id, fill_value=[]) + ) + self.dataset.prefetch([i for s in batches for i in s]) + + if shuffle and fix_batches_to_gpus: + batches = shuffle_batches(batches, self.seed + epoch + self.shard_id) + else: + if shuffle: + batches = shuffle_batches(list(self.frozen_batches), self.seed + epoch) + else: + batches = self.frozen_batches + batches = list( + ShardedIterator(batches, self.num_shards, self.shard_id, fill_value=[]) + ) + + if offset > 0 and offset >= len(batches): + return None + + if self.num_workers > 0: + os.environ["PYTHONWARNINGS"] = "ignore:semaphore_tracker:UserWarning" + + # Create data loader + itr = torch.utils.data.DataLoader( + self.dataset, + collate_fn=self.collate_fn, + batch_sampler=batches[offset:], + num_workers=self.num_workers, + timeout=self.timeout, + pin_memory=True, + ) + + # Wrap with a BufferedIterator if needed + if self.buffer_size > 0: + itr = BufferedIterator(self.buffer_size, itr) + + # Wrap with CountingIterator + itr = CountingIterator(itr, start=offset) + + if self.skip_remainder_batch: + # TODO: Below is a lazy implementation which discard the final batch regardless + # of whether it is a full batch or not. + total_num_itrs = len(batches) - 1 + itr.take(total_num_itrs) + logger.info(f"skip final residual batch, total_num_itrs = {total_num_itrs}") + + return itr + + +class GroupedIterator(CountingIterator): + """Wrapper around an iterable that returns groups (chunks) of items. + + Args: + iterable (iterable): iterable to wrap + chunk_size (int): size of each chunk + skip_remainder_batch (bool, optional): if set, discard the last grouped batch in + each training epoch, as the last grouped batch is usually smaller than + local_batch_size * distributed_word_size * chunk_size (default: ``False``). + Attributes: + n (int): number of elements consumed from this iterator + """ + + def __init__(self, iterable, chunk_size, skip_remainder_batch=False): + if skip_remainder_batch: + total_num_itrs = int(math.floor(len(iterable) / float(chunk_size))) + logger.info( + f"skip final residual batch, grouped total_num_itrs = {total_num_itrs}" + ) + else: + total_num_itrs = int(math.ceil(len(iterable) / float(chunk_size))) + logger.info(f"grouped total_num_itrs = {total_num_itrs}") + + itr = _chunk_iterator(iterable, chunk_size, skip_remainder_batch) + super().__init__( + itr, + start=int(math.ceil(getattr(iterable, "n", 0) / float(chunk_size))), + total=total_num_itrs, + ) + self.chunk_size = chunk_size + + if skip_remainder_batch: + self.take(total_num_itrs) + # TODO: [Hack] Here the grouped iterator modifies the base iterator size so that + # training can move into the next epoch once the grouped iterator is exhausted. + # Double-check this implementation in case unexpected behavior occurs. + iterable.take(total_num_itrs * chunk_size) + + +def _chunk_iterator(itr, chunk_size, skip_remainder_batch=False): + chunk = [] + for x in itr: + chunk.append(x) + if len(chunk) == chunk_size: + yield chunk + chunk = [] + if not skip_remainder_batch and len(chunk) > 0: + yield chunk + + +class ShardedIterator(CountingIterator): + """A sharded wrapper around an iterable, padded to length. + + Args: + iterable (iterable): iterable to wrap + num_shards (int): number of shards to split the iterable into + shard_id (int): which shard to iterator over + fill_value (Any, optional): padding value when the iterable doesn't + evenly divide *num_shards* (default: None). + + Attributes: + n (int): number of elements consumed from this iterator + """ + + def __init__( + self, iterable, num_shards, shard_id, fill_value=None, skip_remainder_batch=None + ): + """ + Args: + skip_remainder_batch: ignored""" + if shard_id < 0 or shard_id >= num_shards: + raise ValueError("shard_id must be between 0 and num_shards") + sharded_len = int(math.ceil(len(iterable) / float(num_shards))) + itr = map( + operator.itemgetter(1), + itertools.zip_longest( + range(sharded_len), + itertools.islice(iterable, shard_id, len(iterable), num_shards), + fillvalue=fill_value, + ), + ) + super().__init__( + itr, + start=int(math.ceil(getattr(iterable, "n", 0) / float(num_shards))), + total=sharded_len, + ) + + +class BackgroundConsumer(Thread): + def __init__(self, queue, source, max_len, cuda_device): + Thread.__init__(self) + + self._queue = queue + self._source = source + self._max_len = max_len + self.count = 0 + self.cuda_device = cuda_device + + def run(self): + # set_device to avoid creation of GPU0 context when using pin_memory + if self.cuda_device is not None: + torch.cuda.set_device(self.cuda_device) + + try: + for item in self._source: + self._queue.put(item) + + # Stop if we reached the maximum length + self.count += 1 + if self._max_len is not None and self.count >= self._max_len: + break + + # Signal the consumer we are done. + self._queue.put(_sentinel) + except Exception as e: + self._queue.put(e) + + +class BufferedIterator(object): + def __init__(self, size, iterable): + self._queue = queue.Queue(size) + self._iterable = iterable + self._consumer = None + + self.start_time = time.time() + self.warning_time = None + + self.total = len(iterable) + + def _create_consumer(self): + self._consumer = BackgroundConsumer( + self._queue, + self._iterable, + self.total, + torch.cuda.current_device() if torch.cuda.is_available() else None, + ) + self._consumer.daemon = True + self._consumer.start() + + def __iter__(self): + return self + + def __len__(self): + return self.total + + def take(self, n): + self.total = min(self.total, n) + # Propagate this change to the underlying iterator + if hasattr(self._iterable, "take"): + self._iterable.take(n) + return self + + def __next__(self): + # Create consumer if not created yet + if self._consumer is None: + self._create_consumer() + + # Notify the user if there is a data loading bottleneck + if self._queue.qsize() < min(2, max(1, self._queue.maxsize // 2)): + if time.time() - self.start_time > 5 * 60: + if ( + self.warning_time is None + or time.time() - self.warning_time > 15 * 60 + ): + logger.debug( + "Data loading buffer is empty or nearly empty. This may " + "indicate a data loading bottleneck, and increasing the " + "number of workers (--num-workers) may help." + ) + self.warning_time = time.time() + + # Get next example + item = self._queue.get(True) + if isinstance(item, Exception): + raise item + if item is _sentinel: + raise StopIteration() + return item + + +class GroupedEpochBatchIterator(EpochBatchIterator): + """Grouped version of EpochBatchIterator + It takes several samplers from different datasets. + Each epoch shuffle the dataset wise sampler individually with different + random seed. The those sub samplers are combined with into + one big samplers with deterministic permutation to mix batches from + different datasets. It will act like EpochBatchIterator but make sure + 1) data from one data set each time + 2) for different workers, they use the same order to fetch the data + so they will use data from the same dataset everytime + mult_rate is used for update_freq > 1 case where we want to make sure update_freq + mini-batches come from same source + """ + + def __init__( + self, + dataset, + collate_fn, + batch_samplers, + seed=1, + num_shards=1, + shard_id=0, + num_workers=0, + epoch=0, + mult_rate=1, + buffer_size=0, + skip_remainder_batch=False, + ): + super().__init__( + dataset, + collate_fn, + batch_samplers, + seed, + num_shards, + shard_id, + num_workers, + epoch, + buffer_size, + skip_remainder_batch=skip_remainder_batch, + ) + # level 0: sub-samplers 1: batch_idx 2: batches + self._frozen_batches = tuple([tuple(sub_batch) for sub_batch in batch_samplers]) + self.step_size = mult_rate * num_shards + + self.lengths = [ + (len(x) // self.step_size) * self.step_size for x in self.frozen_batches + ] + + def __len__(self): + return sum(self.lengths) + + @property + def first_batch(self): + if len(self.frozen_batches) == 0: + raise Exception( + "The dataset is empty. This could indicate " + "that all elements in the dataset have been skipped. " + "Try increasing the max number of allowed tokens or using " + "a larger dataset." + ) + + if self.dataset.supports_fetch_outside_dataloader: + return self.collate_fn([self.dataset[i] for i in self.frozen_batches[0][0]]) + else: + return "DUMMY" + + def _get_iterator_for_epoch( + self, epoch, shuffle, fix_batches_to_gpus=False, offset=0 + ): + def shuffle_batches(batches, seed): + with data_utils.numpy_seed(seed): + np.random.shuffle(batches) + return batches + + def return_full_batches(batch_sets, seed, shuffle): + if shuffle: + batch_sets = [shuffle_batches(list(x), seed) for x in batch_sets] + + batch_sets = [ + batch_sets[i][: self.lengths[i]] for i in range(len(batch_sets)) + ] + batches = list(itertools.chain.from_iterable(batch_sets)) + + if shuffle: + with data_utils.numpy_seed(seed): + idx = np.random.permutation(len(batches) // self.step_size) + if len(idx) * self.step_size != len(batches): + raise ValueError( + "ERROR: %d %d %d %d" + % (len(idx), self.step_size, len(batches), self.shard_id), + ":".join(["%d" % x for x in self.lengths]), + ) + mini_shards = [ + batches[i * self.step_size : (i + 1) * self.step_size] + for i in idx + ] + batches = list(itertools.chain.from_iterable(mini_shards)) + + return batches + + if self._supports_prefetch: + raise NotImplementedError("To be implemented") + else: + batches = return_full_batches( + self.frozen_batches, self.seed + epoch, shuffle + ) + batches = list( + ShardedIterator(batches, self.num_shards, self.shard_id, fill_value=[]) + ) + + if offset > 0 and offset >= len(batches): + return None + + if self.num_workers > 0: + os.environ["PYTHONWARNINGS"] = "ignore:semaphore_tracker:UserWarning" + + itr = torch.utils.data.DataLoader( + self.dataset, + collate_fn=self.collate_fn, + batch_sampler=batches[offset:], + num_workers=self.num_workers, + ) + if self.buffer_size > 0: + itr = BufferedIterator(self.buffer_size, itr) + + return CountingIterator(itr, start=offset) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/language_pair_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/language_pair_dataset.py new file mode 100644 index 00000000..fd356ddd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/language_pair_dataset.py @@ -0,0 +1,477 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import numpy as np +import torch +from fairseq.data import FairseqDataset, data_utils + + +logger = logging.getLogger(__name__) + + +def collate( + samples, + pad_idx, + eos_idx, + left_pad_source=True, + left_pad_target=False, + input_feeding=True, + pad_to_length=None, + pad_to_multiple=1, +): + if len(samples) == 0: + return {} + + def merge(key, left_pad, move_eos_to_beginning=False, pad_to_length=None): + return data_utils.collate_tokens( + [s[key] for s in samples], + pad_idx, + eos_idx, + left_pad, + move_eos_to_beginning, + pad_to_length=pad_to_length, + pad_to_multiple=pad_to_multiple, + ) + + def check_alignment(alignment, src_len, tgt_len): + if alignment is None or len(alignment) == 0: + return False + if ( + alignment[:, 0].max().item() >= src_len - 1 + or alignment[:, 1].max().item() >= tgt_len - 1 + ): + logger.warning("alignment size mismatch found, skipping alignment!") + return False + return True + + def compute_alignment_weights(alignments): + """ + Given a tensor of shape [:, 2] containing the source-target indices + corresponding to the alignments, a weight vector containing the + inverse frequency of each target index is computed. + For e.g. if alignments = [[5, 7], [2, 3], [1, 3], [4, 2]], then + a tensor containing [1., 0.5, 0.5, 1] should be returned (since target + index 3 is repeated twice) + """ + align_tgt = alignments[:, 1] + _, align_tgt_i, align_tgt_c = torch.unique( + align_tgt, return_inverse=True, return_counts=True + ) + align_weights = align_tgt_c[align_tgt_i[np.arange(len(align_tgt))]] + return 1.0 / align_weights.float() + + id = torch.LongTensor([s["id"] for s in samples]) + src_tokens = merge( + "source", + left_pad=left_pad_source, + pad_to_length=pad_to_length["source"] if pad_to_length is not None else None, + ) + # sort by descending source length + src_lengths = torch.LongTensor( + [s["source"].ne(pad_idx).long().sum() for s in samples] + ) + src_lengths, sort_order = src_lengths.sort(descending=True) + id = id.index_select(0, sort_order) + src_tokens = src_tokens.index_select(0, sort_order) + + prev_output_tokens = None + target = None + if samples[0].get("target", None) is not None: + target = merge( + "target", + left_pad=left_pad_target, + pad_to_length=pad_to_length["target"] + if pad_to_length is not None + else None, + ) + target = target.index_select(0, sort_order) + tgt_lengths = torch.LongTensor( + [s["target"].ne(pad_idx).long().sum() for s in samples] + ).index_select(0, sort_order) + ntokens = tgt_lengths.sum().item() + + if samples[0].get("prev_output_tokens", None) is not None: + prev_output_tokens = merge("prev_output_tokens", left_pad=left_pad_target) + elif input_feeding: + # we create a shifted version of targets for feeding the + # previous output token(s) into the next decoder step + prev_output_tokens = merge( + "target", + left_pad=left_pad_target, + move_eos_to_beginning=True, + pad_to_length=pad_to_length["target"] + if pad_to_length is not None + else None, + ) + else: + ntokens = src_lengths.sum().item() + + batch = { + "id": id, + "nsentences": len(samples), + "ntokens": ntokens, + "net_input": { + "src_tokens": src_tokens, + "src_lengths": src_lengths, + }, + "target": target, + } + if prev_output_tokens is not None: + batch["net_input"]["prev_output_tokens"] = prev_output_tokens.index_select( + 0, sort_order + ) + + if samples[0].get("alignment", None) is not None: + bsz, tgt_sz = batch["target"].shape + src_sz = batch["net_input"]["src_tokens"].shape[1] + + offsets = torch.zeros((len(sort_order), 2), dtype=torch.long) + offsets[:, 1] += torch.arange(len(sort_order), dtype=torch.long) * tgt_sz + if left_pad_source: + offsets[:, 0] += src_sz - src_lengths + if left_pad_target: + offsets[:, 1] += tgt_sz - tgt_lengths + + alignments = [ + alignment + offset + for align_idx, offset, src_len, tgt_len in zip( + sort_order, offsets, src_lengths, tgt_lengths + ) + for alignment in [samples[align_idx]["alignment"].view(-1, 2)] + if check_alignment(alignment, src_len, tgt_len) + ] + + if len(alignments) > 0: + alignments = torch.cat(alignments, dim=0) + align_weights = compute_alignment_weights(alignments) + + batch["alignments"] = alignments + batch["align_weights"] = align_weights + + if samples[0].get("constraints", None) is not None: + # Collate the packed constraints across the samples, padding to + # the length of the longest sample. + lens = [sample.get("constraints").size(0) for sample in samples] + max_len = max(lens) + constraints = torch.zeros((len(samples), max(lens))).long() + for i, sample in enumerate(samples): + constraints[i, 0 : lens[i]] = samples[i].get("constraints") + batch["constraints"] = constraints.index_select(0, sort_order) + + return batch + + +class LanguagePairDataset(FairseqDataset): + """ + A pair of torch.utils.data.Datasets. + + Args: + src (torch.utils.data.Dataset): source dataset to wrap + src_sizes (List[int]): source sentence lengths + src_dict (~fairseq.data.Dictionary): source vocabulary + tgt (torch.utils.data.Dataset, optional): target dataset to wrap + tgt_sizes (List[int], optional): target sentence lengths + tgt_dict (~fairseq.data.Dictionary, optional): target vocabulary + left_pad_source (bool, optional): pad source tensors on the left side + (default: True). + left_pad_target (bool, optional): pad target tensors on the left side + (default: False). + shuffle (bool, optional): shuffle dataset elements before batching + (default: True). + input_feeding (bool, optional): create a shifted version of the targets + to be passed into the model for teacher forcing (default: True). + remove_eos_from_source (bool, optional): if set, removes eos from end + of source if it's present (default: False). + append_eos_to_target (bool, optional): if set, appends eos to end of + target if it's absent (default: False). + align_dataset (torch.utils.data.Dataset, optional): dataset + containing alignments. + constraints (Tensor, optional): 2d tensor with a concatenated, zero- + delimited list of constraints for each sentence. + append_bos (bool, optional): if set, appends bos to the beginning of + source/target sentence. + num_buckets (int, optional): if set to a value greater than 0, then + batches will be bucketed into the given number of batch shapes. + src_lang_id (int, optional): source language ID, if set, the collated batch + will contain a field 'src_lang_id' in 'net_input' which indicates the + source language of the samples. + tgt_lang_id (int, optional): target language ID, if set, the collated batch + will contain a field 'tgt_lang_id' which indicates the target language + of the samples. + """ + + def __init__( + self, + src, + src_sizes, + src_dict, + tgt=None, + tgt_sizes=None, + tgt_dict=None, + left_pad_source=True, + left_pad_target=False, + shuffle=True, + input_feeding=True, + remove_eos_from_source=False, + append_eos_to_target=False, + align_dataset=None, + constraints=None, + append_bos=False, + eos=None, + num_buckets=0, + src_lang_id=None, + tgt_lang_id=None, + pad_to_multiple=1, + ): + if tgt_dict is not None: + assert src_dict.pad() == tgt_dict.pad() + assert src_dict.eos() == tgt_dict.eos() + assert src_dict.unk() == tgt_dict.unk() + if tgt is not None: + assert len(src) == len( + tgt + ), "Source and target must contain the same number of examples" + self.src = src + self.tgt = tgt + self.src_sizes = np.array(src_sizes) + self.tgt_sizes = np.array(tgt_sizes) if tgt_sizes is not None else None + self.sizes = ( + np.vstack((self.src_sizes, self.tgt_sizes)).T + if self.tgt_sizes is not None + else self.src_sizes + ) + self.src_dict = src_dict + self.tgt_dict = tgt_dict + self.left_pad_source = left_pad_source + self.left_pad_target = left_pad_target + self.shuffle = shuffle + self.input_feeding = input_feeding + self.remove_eos_from_source = remove_eos_from_source + self.append_eos_to_target = append_eos_to_target + self.align_dataset = align_dataset + if self.align_dataset is not None: + assert ( + self.tgt_sizes is not None + ), "Both source and target needed when alignments are provided" + self.constraints = constraints + self.append_bos = append_bos + self.eos = eos if eos is not None else src_dict.eos() + self.src_lang_id = src_lang_id + self.tgt_lang_id = tgt_lang_id + if num_buckets > 0: + from fairseq.data import BucketPadLengthDataset + + self.src = BucketPadLengthDataset( + self.src, + sizes=self.src_sizes, + num_buckets=num_buckets, + pad_idx=self.src_dict.pad(), + left_pad=self.left_pad_source, + ) + self.src_sizes = self.src.sizes + logger.info("bucketing source lengths: {}".format(list(self.src.buckets))) + if self.tgt is not None: + self.tgt = BucketPadLengthDataset( + self.tgt, + sizes=self.tgt_sizes, + num_buckets=num_buckets, + pad_idx=self.tgt_dict.pad(), + left_pad=self.left_pad_target, + ) + self.tgt_sizes = self.tgt.sizes + logger.info( + "bucketing target lengths: {}".format(list(self.tgt.buckets)) + ) + + # determine bucket sizes using self.num_tokens, which will return + # the padded lengths (thanks to BucketPadLengthDataset) + num_tokens = np.vectorize(self.num_tokens, otypes=[np.compat.long]) + self.bucketed_num_tokens = num_tokens(np.arange(len(self.src))) + self.buckets = [ + (None, num_tokens) for num_tokens in np.unique(self.bucketed_num_tokens) + ] + else: + self.buckets = None + self.pad_to_multiple = pad_to_multiple + + def get_batch_shapes(self): + return self.buckets + + def __getitem__(self, index): + tgt_item = self.tgt[index] if self.tgt is not None else None + src_item = self.src[index] + # Append EOS to end of tgt sentence if it does not have an EOS and remove + # EOS from end of src sentence if it exists. This is useful when we use + # use existing datasets for opposite directions i.e., when we want to + # use tgt_dataset as src_dataset and vice versa + if self.append_eos_to_target: + eos = self.tgt_dict.eos() if self.tgt_dict else self.src_dict.eos() + if self.tgt and self.tgt[index][-1] != eos: + tgt_item = torch.cat([self.tgt[index], torch.LongTensor([eos])]) + + if self.append_bos: + bos = self.tgt_dict.bos() if self.tgt_dict else self.src_dict.bos() + if self.tgt and self.tgt[index][0] != bos: + tgt_item = torch.cat([torch.LongTensor([bos]), self.tgt[index]]) + + bos = self.src_dict.bos() + if self.src[index][0] != bos: + src_item = torch.cat([torch.LongTensor([bos]), self.src[index]]) + + if self.remove_eos_from_source: + eos = self.src_dict.eos() + if self.src[index][-1] == eos: + src_item = self.src[index][:-1] + + example = { + "id": index, + "source": src_item, + "target": tgt_item, + } + if self.align_dataset is not None: + example["alignment"] = self.align_dataset[index] + if self.constraints is not None: + example["constraints"] = self.constraints[index] + return example + + def __len__(self): + return len(self.src) + + def collater(self, samples, pad_to_length=None): + """Merge a list of samples to form a mini-batch. + + Args: + samples (List[dict]): samples to collate + pad_to_length (dict, optional): a dictionary of + {'source': source_pad_to_length, 'target': target_pad_to_length} + to indicate the max length to pad to in source and target respectively. + + Returns: + dict: a mini-batch with the following keys: + + - `id` (LongTensor): example IDs in the original input order + - `ntokens` (int): total number of tokens in the batch + - `net_input` (dict): the input to the Model, containing keys: + + - `src_tokens` (LongTensor): a padded 2D Tensor of tokens in + the source sentence of shape `(bsz, src_len)`. Padding will + appear on the left if *left_pad_source* is ``True``. + - `src_lengths` (LongTensor): 1D Tensor of the unpadded + lengths of each source sentence of shape `(bsz)` + - `prev_output_tokens` (LongTensor): a padded 2D Tensor of + tokens in the target sentence, shifted right by one + position for teacher forcing, of shape `(bsz, tgt_len)`. + This key will not be present if *input_feeding* is + ``False``. Padding will appear on the left if + *left_pad_target* is ``True``. + - `src_lang_id` (LongTensor): a long Tensor which contains source + language IDs of each sample in the batch + + - `target` (LongTensor): a padded 2D Tensor of tokens in the + target sentence of shape `(bsz, tgt_len)`. Padding will appear + on the left if *left_pad_target* is ``True``. + - `tgt_lang_id` (LongTensor): a long Tensor which contains target language + IDs of each sample in the batch + """ + res = collate( + samples, + pad_idx=self.src_dict.pad(), + eos_idx=self.eos, + left_pad_source=self.left_pad_source, + left_pad_target=self.left_pad_target, + input_feeding=self.input_feeding, + pad_to_length=pad_to_length, + pad_to_multiple=self.pad_to_multiple, + ) + if self.src_lang_id is not None or self.tgt_lang_id is not None: + src_tokens = res["net_input"]["src_tokens"] + bsz = src_tokens.size(0) + if self.src_lang_id is not None: + res["net_input"]["src_lang_id"] = ( + torch.LongTensor([[self.src_lang_id]]).expand(bsz, 1).to(src_tokens) + ) + if self.tgt_lang_id is not None: + res["tgt_lang_id"] = ( + torch.LongTensor([[self.tgt_lang_id]]).expand(bsz, 1).to(src_tokens) + ) + return res + + def num_tokens(self, index): + """Return the number of tokens in a sample. This value is used to + enforce ``--max-tokens`` during batching.""" + return max( + self.src_sizes[index], + self.tgt_sizes[index] if self.tgt_sizes is not None else 0, + ) + + def num_tokens_vec(self, indices): + """Return the number of tokens for a set of positions defined by indices. + This value is used to enforce ``--max-tokens`` during batching.""" + sizes = self.src_sizes[indices] + if self.tgt_sizes is not None: + sizes = np.maximum(sizes, self.tgt_sizes[indices]) + return sizes + + def size(self, index): + """Return an example's size as a float or tuple. This value is used when + filtering a dataset with ``--max-positions``.""" + return ( + self.src_sizes[index], + self.tgt_sizes[index] if self.tgt_sizes is not None else 0, + ) + + def ordered_indices(self): + """Return an ordered list of indices. Batches will be constructed based + on this order.""" + if self.shuffle: + indices = np.random.permutation(len(self)).astype(np.int64) + else: + indices = np.arange(len(self), dtype=np.int64) + if self.buckets is None: + # sort by target length, then source length + if self.tgt_sizes is not None: + indices = indices[np.argsort(self.tgt_sizes[indices], kind="mergesort")] + return indices[np.argsort(self.src_sizes[indices], kind="mergesort")] + else: + # sort by bucketed_num_tokens, which is: + # max(padded_src_len, padded_tgt_len) + return indices[ + np.argsort(self.bucketed_num_tokens[indices], kind="mergesort") + ] + + @property + def supports_prefetch(self): + return getattr(self.src, "supports_prefetch", False) and ( + getattr(self.tgt, "supports_prefetch", False) or self.tgt is None + ) + + def prefetch(self, indices): + self.src.prefetch(indices) + if self.tgt is not None: + self.tgt.prefetch(indices) + if self.align_dataset is not None: + self.align_dataset.prefetch(indices) + + def filter_indices_by_size(self, indices, max_sizes): + """Filter a list of sample indices. Remove those that are longer + than specified in max_sizes. + + Args: + indices (np.array): original array of sample indices + max_sizes (int or list[int] or tuple[int]): max sample size, + can be defined separately for src and tgt (then list or tuple) + + Returns: + np.array: filtered sample array + list: list of removed indices + """ + return data_utils.filter_paired_dataset_indices_by_size( + self.src_sizes, + self.tgt_sizes, + indices, + max_sizes, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/legacy/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/data/legacy/__init__.py new file mode 100644 index 00000000..9bd5c72b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/legacy/__init__.py @@ -0,0 +1,16 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .block_pair_dataset import BlockPairDataset +from .masked_lm_dataset import MaskedLMDataset +from .masked_lm_dictionary import BertDictionary, MaskedLMDictionary + + +__all__ = [ + "BertDictionary", + "BlockPairDataset", + "MaskedLMDataset", + "MaskedLMDictionary", +] diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/legacy/block_pair_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/legacy/block_pair_dataset.py new file mode 100644 index 00000000..ba069b46 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/legacy/block_pair_dataset.py @@ -0,0 +1,311 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import numpy as np +import torch +from fairseq.data import FairseqDataset + + +class BlockPairDataset(FairseqDataset): + """Break a Dataset of tokens into sentence pair blocks for next sentence + prediction as well as masked language model. + + High-level logics are: + 1. break input tensor to tensor blocks + 2. pair the blocks with 50% next sentence and 50% random sentence + 3. return paired blocks as well as related segment labels + + Args: + dataset (~torch.utils.data.Dataset): dataset to break into blocks + sizes: array of sentence lengths + dictionary: dictionary for the task + block_size: maximum block size + break_mode: mode for breaking copurs into block pairs. currently we support + 2 modes + doc: respect document boundaries and each part of the pair should belong to on document + none: don't respect any boundary and cut tokens evenly + short_seq_prob: probability for generating shorter block pairs + doc_break_size: Size for empty line separating documents. Typically 1 if + the sentences have eos, 0 otherwise. + """ + + def __init__( + self, + dataset, + dictionary, + sizes, + block_size, + break_mode="doc", + short_seq_prob=0.1, + doc_break_size=1, + ): + super().__init__() + self.dataset = dataset + self.pad = dictionary.pad() + self.eos = dictionary.eos() + self.cls = dictionary.cls() + self.mask = dictionary.mask() + self.sep = dictionary.sep() + self.break_mode = break_mode + self.dictionary = dictionary + self.short_seq_prob = short_seq_prob + self.block_indices = [] + + assert len(dataset) == len(sizes) + + if break_mode == "doc": + cur_doc = [] + for sent_id, sz in enumerate(sizes): + assert doc_break_size == 0 or sz != 0, ( + "when doc_break_size is non-zero, we expect documents to be" + "separated by a blank line with a single eos." + ) + # empty line as document separator + if sz == doc_break_size: + if len(cur_doc) == 0: + continue + self.block_indices.append(cur_doc) + cur_doc = [] + else: + cur_doc.append(sent_id) + max_num_tokens = block_size - 3 # Account for [CLS], [SEP], [SEP] + self.sent_pairs = [] + self.sizes = [] + for doc_id, doc in enumerate(self.block_indices): + self._generate_sentence_pair(doc, doc_id, max_num_tokens, sizes) + elif break_mode is None or break_mode == "none": + # each block should have half of the block size since we are constructing block pair + sent_length = (block_size - 3) // 2 + total_len = sum(dataset.sizes) + length = math.ceil(total_len / sent_length) + + def block_at(i): + start = i * sent_length + end = min(start + sent_length, total_len) + return (start, end) + + sent_indices = np.array([block_at(i) for i in range(length)]) + sent_sizes = np.array([e - s for s, e in sent_indices]) + dataset_index = self._sent_to_dataset_index(sent_sizes) + + # pair sentences + self._pair_sentences(dataset_index) + else: + raise ValueError("Invalid break_mode: " + break_mode) + + def _pair_sentences(self, dataset_index): + """ + Give a list of evenly cut blocks/sentences, pair these sentences with 50% + consecutive sentences and 50% random sentences. + This is used for none break mode + """ + # pair sentences + for sent_id, sent in enumerate(dataset_index): + next_sent_label = ( + 1 if np.random.rand() > 0.5 and sent_id != len(dataset_index) - 1 else 0 + ) + if next_sent_label: + next_sent = dataset_index[sent_id + 1] + else: + next_sent = dataset_index[ + self._skip_sampling(len(dataset_index), [sent_id, sent_id + 1]) + ] + self.sent_pairs.append((sent, next_sent, next_sent_label)) + + # The current blocks don't include the special tokens but the + # sizes already account for this + self.sizes.append(3 + sent[3] + next_sent[3]) + + def _sent_to_dataset_index(self, sent_sizes): + """ + Build index mapping block indices to the underlying dataset indices + """ + dataset_index = [] + ds_idx, ds_remaining = -1, 0 + for to_consume in sent_sizes: + sent_size = to_consume + if ds_remaining == 0: + ds_idx += 1 + ds_remaining = sent_sizes[ds_idx] + start_ds_idx = ds_idx + start_offset = sent_sizes[ds_idx] - ds_remaining + while to_consume > ds_remaining: + to_consume -= ds_remaining + ds_idx += 1 + ds_remaining = sent_sizes[ds_idx] + ds_remaining -= to_consume + dataset_index.append( + ( + start_ds_idx, # starting index in dataset + start_offset, # starting offset within starting index + ds_idx, # ending index in dataset + sent_size, # sentence length + ) + ) + assert ds_remaining == 0 + assert ds_idx == len(self.dataset) - 1 + return dataset_index + + def _generate_sentence_pair(self, doc, doc_id, max_num_tokens, sizes): + """ + Go through a single document and genrate sentence paris from it + """ + current_chunk = [] + current_length = 0 + curr = 0 + # To provide more randomness, we decrease target seq length for parts of + # samples (10% by default). Note that max_num_tokens is the hard threshold + # for batching and will never be changed. + target_seq_length = max_num_tokens + if np.random.random() < self.short_seq_prob: + target_seq_length = np.random.randint(2, max_num_tokens) + # loop through all sentences in document + while curr < len(doc): + sent_id = doc[curr] + current_chunk.append(sent_id) + current_length = sum(sizes[current_chunk]) + # split chunk and generate pair when exceed target_seq_length or + # finish the loop + if curr == len(doc) - 1 or current_length >= target_seq_length: + # split the chunk into 2 parts + a_end = 1 + if len(current_chunk) > 2: + a_end = np.random.randint(1, len(current_chunk) - 1) + sent_a = current_chunk[:a_end] + len_a = sum(sizes[sent_a]) + # generate next sentence label, note that if there is only 1 sentence + # in current chunk, label is always 0 + next_sent_label = ( + 1 if np.random.rand() > 0.5 and len(current_chunk) != 1 else 0 + ) + if not next_sent_label: + # if next sentence label is 0, sample sent_b from a random doc + target_b_length = target_seq_length - len_a + rand_doc_id = self._skip_sampling(len(self.block_indices), [doc_id]) + random_doc = self.block_indices[rand_doc_id] + random_start = np.random.randint(0, len(random_doc)) + sent_b = [] + len_b = 0 + for j in range(random_start, len(random_doc)): + sent_b.append(random_doc[j]) + len_b = sum(sizes[sent_b]) + if len_b >= target_b_length: + break + # return the second part of the chunk since it's not used + num_unused_segments = len(current_chunk) - a_end + curr -= num_unused_segments + else: + # if next sentence label is 1, use the second part of chunk as sent_B + sent_b = current_chunk[a_end:] + len_b = sum(sizes[sent_b]) + # currently sent_a and sent_B may be longer than max_num_tokens, + # truncate them and return block idx and offsets for them + sent_a, sent_b = self._truncate_sentences( + sent_a, sent_b, max_num_tokens + ) + self.sent_pairs.append((sent_a, sent_b, next_sent_label)) + self.sizes.append(3 + sent_a[3] + sent_b[3]) + current_chunk = [] + curr += 1 + + def _skip_sampling(self, total, skip_ids): + """ + Generate a random integer which is not in skip_ids. Sample range is [0, total) + TODO: ids in skip_ids should be consecutive, we can extend it to more generic version later + """ + rand_id = np.random.randint(total - len(skip_ids)) + return rand_id if rand_id < min(skip_ids) else rand_id + len(skip_ids) + + def _truncate_sentences(self, sent_a, sent_b, max_num_tokens): + """ + Trancate a pair of sentence to limit total length under max_num_tokens + Logics: + 1. Truncate longer sentence + 2. Tokens to be truncated could be at the beginning or the end of the sentnce + Returns: + Truncated sentences represented by dataset idx + """ + len_a, len_b = sum(self.dataset.sizes[sent_a]), sum(self.dataset.sizes[sent_b]) + front_cut_a = front_cut_b = end_cut_a = end_cut_b = 0 + + while True: + total_length = ( + len_a + len_b - front_cut_a - front_cut_b - end_cut_a - end_cut_b + ) + if total_length <= max_num_tokens: + break + + if len_a - front_cut_a - end_cut_a > len_b - front_cut_b - end_cut_b: + if np.random.rand() < 0.5: + front_cut_a += 1 + else: + end_cut_a += 1 + else: + if np.random.rand() < 0.5: + front_cut_b += 1 + else: + end_cut_b += 1 + + # calculate ds indices as well as offsets and return + truncated_sent_a = self._cut_sentence(sent_a, front_cut_a, end_cut_a) + truncated_sent_b = self._cut_sentence(sent_b, front_cut_b, end_cut_b) + return truncated_sent_a, truncated_sent_b + + def _cut_sentence(self, sent, front_cut, end_cut): + """ + Cut a sentence based on the numbers of tokens to be cut from beginning and end + Represent the sentence as dataset idx and return + """ + start_ds_idx, end_ds_idx, offset = sent[0], sent[-1], 0 + target_len = sum(self.dataset.sizes[sent]) - front_cut - end_cut + while front_cut > 0: + if self.dataset.sizes[start_ds_idx] > front_cut: + offset += front_cut + break + else: + front_cut -= self.dataset.sizes[start_ds_idx] + start_ds_idx += 1 + while end_cut > 0: + if self.dataset.sizes[end_ds_idx] > end_cut: + break + else: + end_cut -= self.dataset.sizes[end_ds_idx] + end_ds_idx -= 1 + return start_ds_idx, offset, end_ds_idx, target_len + + def _fetch_block(self, start_ds_idx, offset, end_ds_idx, length): + """ + Fetch a block of tokens based on its dataset idx + """ + buffer = torch.cat( + [self.dataset[idx] for idx in range(start_ds_idx, end_ds_idx + 1)] + ) + s, e = offset, offset + length + return buffer[s:e] + + def __getitem__(self, index): + block1, block2, next_sent_label = self.sent_pairs[index] + block1 = self._fetch_block(*block1) + block2 = self._fetch_block(*block2) + return block1, block2, next_sent_label + + def __len__(self): + return len(self.sizes) + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def prefetch(self, indices): + prefetch_idx = set() + for index in indices: + for block1, block2, _ in [self.sent_pairs[index]]: + for ds_idx in range(block1[0], block1[2] + 1): + prefetch_idx.add(ds_idx) + for ds_idx in range(block2[0], block2[2] + 1): + prefetch_idx.add(ds_idx) + self.dataset.prefetch(prefetch_idx) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/legacy/masked_lm_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/legacy/masked_lm_dataset.py new file mode 100644 index 00000000..dd8ea2c6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/legacy/masked_lm_dataset.py @@ -0,0 +1,303 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from typing import Dict, List, Tuple + +import numpy as np +import torch +from fairseq.data import Dictionary, FairseqDataset, data_utils +from fairseq.data.concat_dataset import ConcatDataset +from fairseq.data.legacy.block_pair_dataset import BlockPairDataset +from fairseq.data.token_block_dataset import TokenBlockDataset + + +class MaskedLMDataset(FairseqDataset): + """ + A wrapper Dataset for masked language modelling. The dataset + wraps around TokenBlockDataset or BlockedPairDataset and creates a batch + where the input blocks are masked according to the specified masking + probability. Additionally the batch can also contain sentence level targets + if this is specified. + + Args: + dataset: Dataset which generates blocks of data. Only BlockPairDataset + and TokenBlockDataset are supported. + sizes: Sentence lengths + vocab: Dictionary with the vocabulary and special tokens. + pad_idx: Id of padding token in dictionary + mask_idx: Id of mask token in dictionary + classif_token_idx: Id of classification token in dictionary. This is the + token associated with the sentence embedding (Eg: CLS for BERT) + sep_token_idx: Id of separator token in dictionary + (Eg: SEP in BERT) + seed: Seed for random number generator for reproducibility. + shuffle: Shuffle the elements before batching. + has_pairs: Specifies whether the underlying dataset + generates a pair of blocks along with a sentence_target or not. + Setting it to True assumes that the underlying dataset generates a + label for the pair of sentences which is surfaced as + sentence_target. The default value assumes a single block with no + sentence target. + segment_id: An optional segment id for filling in the segment labels + when we are in the single block setting (Eg: XLM). Default is 0. + masking_ratio: specifies what percentage of the blocks should be masked. + masking_prob: specifies the probability of a given token being + replaced with the "MASK" token. + random_token_prob: specifies the probability of a given token being + replaced by a random token from the vocabulary. + """ + + def __init__( + self, + dataset: FairseqDataset, + sizes: np.ndarray, + vocab: Dictionary, + pad_idx: int, + mask_idx: int, + classif_token_idx: int, + sep_token_idx: int, + seed: int = 1, + shuffle: bool = True, + has_pairs: bool = True, + segment_id: int = 0, + masking_ratio: float = 0.15, + masking_prob: float = 0.8, + random_token_prob: float = 0.1, + ): + # Make sure the input datasets are the ones supported + assert ( + isinstance(dataset, TokenBlockDataset) + or isinstance(dataset, BlockPairDataset) + or isinstance(dataset, ConcatDataset) + ), ( + "MaskedLMDataset only wraps TokenBlockDataset or BlockPairDataset or " + "ConcatDataset" + ) + + self.dataset = dataset + self.sizes = np.array(sizes) + self.vocab = vocab + self.pad_idx = pad_idx + self.mask_idx = mask_idx + self.classif_token_idx = classif_token_idx + self.sep_token_idx = sep_token_idx + self.shuffle = shuffle + self.seed = seed + self.has_pairs = has_pairs + self.segment_id = segment_id + self.masking_ratio = masking_ratio + self.masking_prob = masking_prob + self.random_token_prob = random_token_prob + + # If we have only one block then sizes needs to be updated to include + # the classification token + if not has_pairs: + self.sizes = self.sizes + 1 + + def __getitem__(self, index: int): + # if has_pairs, then expect 2 blocks and a sentence target + if self.has_pairs: + (block_one, block_two, sentence_target) = self.dataset[index] + else: + block_one = self.dataset[index] + + return { + "id": index, + "block_one": block_one, + "block_two": block_two if self.has_pairs else None, + "sentence_target": sentence_target if self.has_pairs else None, + } + + def __len__(self): + return len(self.dataset) + + def _mask_block( + self, + sentence: np.ndarray, + mask_idx: int, + pad_idx: int, + dictionary_token_range: Tuple, + ): + """ + Mask tokens for Masked Language Model training + Samples mask_ratio tokens that will be predicted by LM. + + Note:This function may not be efficient enough since we had multiple + conversions between np and torch, we can replace them with torch + operators later. + + Args: + sentence: 1d tensor to be masked + mask_idx: index to use for masking the sentence + pad_idx: index to use for masking the target for tokens we aren't + predicting + dictionary_token_range: range of indices in dictionary which can + be used for random word replacement + (e.g. without special characters) + Return: + masked_sent: masked sentence + target: target with words which we are not predicting replaced + by pad_idx + """ + masked_sent = np.copy(sentence) + sent_length = len(sentence) + mask_num = math.ceil(sent_length * self.masking_ratio) + mask = np.random.choice(sent_length, mask_num, replace=False) + target = np.copy(sentence) + + for i in range(sent_length): + if i in mask: + rand = np.random.random() + + # replace with mask if probability is less than masking_prob + # (Eg: 0.8) + if rand < self.masking_prob: + masked_sent[i] = mask_idx + + # replace with random token if probability is less than + # masking_prob + random_token_prob (Eg: 0.9) + elif rand < (self.masking_prob + self.random_token_prob): + # sample random token from dictionary + masked_sent[i] = np.random.randint( + dictionary_token_range[0], dictionary_token_range[1] + ) + else: + target[i] = pad_idx + + return masked_sent, target + + def _collate(self, samples: List[Dict], pad_idx: int, eos_idx: int): + """ + Does the heavy lifting for creating a batch from the input list of + examples. The logic is as follows: + 1. Mask the input blocks. In case has_pair is True then we have 2 + blocks to mask. + 2. Prepend the first masked block tensor with the special token + used as sentence embedding. Eg: CLS in BERT. This happens + irrespective of the value of has_pair. + 3. If has_pair is True, then append the first masked block with the + special separator token (eg: SEP for BERT) and compute segment + label accordingly. In this case, also append the second masked + block with this special separator token and compute its segment + label. + 4. For the targets tensor, prepend and append with padding index + accordingly. + 5. Concatenate all tensors. + """ + if len(samples) == 0: + return {} + # To ensure determinism, we reset the state of the PRNG after every + # batch based on the seed and the first id of the batch. This ensures + # that across epochs we get the same mask for the same example. This + # is needed for reproducibility and is how BERT does masking + # TODO: Can we add deteminism without this constraint? + with data_utils.numpy_seed(self.seed + samples[0]["id"]): + for s in samples: + + # token range is needed for replacing with random token during + # masking + token_range = (self.vocab.nspecial, len(self.vocab)) + + # mask according to specified probabilities. + masked_blk_one, masked_tgt_one = self._mask_block( + s["block_one"], + self.mask_idx, + self.pad_idx, + token_range, + ) + + tokens = np.concatenate([[self.classif_token_idx], masked_blk_one]) + targets = np.concatenate([[self.pad_idx], masked_tgt_one]) + segments = np.ones(len(tokens)) * self.segment_id + + # if has_pairs is True then we need to add the SEP token to both + # the blocks after masking and re-compute segments based on the new + # lengths. + if self.has_pairs: + tokens_one = np.concatenate([tokens, [self.sep_token_idx]]) + targets_one = np.concatenate([targets, [self.pad_idx]]) + + masked_blk_two, masked_tgt_two = self._mask_block( + s["block_two"], self.mask_idx, self.pad_idx, token_range + ) + tokens_two = np.concatenate([masked_blk_two, [self.sep_token_idx]]) + targets_two = np.concatenate([masked_tgt_two, [self.pad_idx]]) + + # block + 1 sep + 1 special (CLS) + segments_one = np.zeros(len(tokens_one)) + # block + 1 sep + segments_two = np.ones(len(tokens_two)) + + tokens = np.concatenate([tokens_one, tokens_two]) + targets = np.concatenate([targets_one, targets_two]) + segments = np.concatenate([segments_one, segments_two]) + + s["source"] = torch.LongTensor(tokens) + s["segment_labels"] = torch.LongTensor(segments) + s["lm_target"] = torch.LongTensor(targets) + + def merge(key): + return data_utils.collate_tokens( + [s[key] for s in samples], pad_idx, eos_idx, left_pad=False + ) + + return { + "id": torch.LongTensor([s["id"] for s in samples]), + "ntokens": sum(len(s["source"]) for s in samples), + "net_input": { + "src_tokens": merge("source"), + "segment_labels": merge("segment_labels"), + }, + "lm_target": merge("lm_target"), + "sentence_target": torch.LongTensor([s["sentence_target"] for s in samples]) + if self.has_pairs + else None, + "nsentences": len(samples), + } + + def collater(self, samples: List[Dict]): + """Merge a list of samples to form a mini-batch. + + Args: + samples (List[dict]): samples to collate + + Returns: + dict: a mini-batch of data + """ + return self._collate(samples, self.vocab.pad(), self.vocab.eos()) + + def num_tokens(self, index: int): + """ + Return the number of tokens in a sample. This value is used to + enforce max-tokens during batching. + """ + return self.sizes[index] + + def size(self, index: int): + """ + Return an example's size as a float or tuple. This value is used when + filtering a dataset with max-positions. + """ + return self.sizes[index] + + def ordered_indices(self): + """ + Return an ordered list of indices. Batches will be constructed based + on this order. + """ + if self.shuffle: + return np.random.permutation(len(self)) + else: + order = [np.arange(len(self))] + order.append(self.sizes) + return np.lexsort(order) + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def prefetch(self, indices): + self.dataset.prefetch(indices) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/legacy/masked_lm_dictionary.py b/PyTorch/NLP/new-Transformer/fairseq/data/legacy/masked_lm_dictionary.py new file mode 100644 index 00000000..dee88f7a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/legacy/masked_lm_dictionary.py @@ -0,0 +1,60 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.data import Dictionary + + +class MaskedLMDictionary(Dictionary): + """ + Dictionary for Masked Language Modelling tasks. This extends Dictionary by + adding the mask symbol. + """ + + def __init__( + self, + pad="", + eos="", + unk="", + mask="", + ): + super().__init__(pad=pad, eos=eos, unk=unk) + self.mask_word = mask + self.mask_index = self.add_symbol(mask) + self.nspecial = len(self.symbols) + + def mask(self): + """Helper to get index of mask symbol""" + return self.mask_index + + +class BertDictionary(MaskedLMDictionary): + """ + Dictionary for BERT task. This extends MaskedLMDictionary by adding support + for cls and sep symbols. + """ + + def __init__( + self, + pad="", + eos="", + unk="", + mask="", + cls="", + sep="", + ): + super().__init__(pad=pad, eos=eos, unk=unk, mask=mask) + self.cls_word = cls + self.sep_word = sep + self.cls_index = self.add_symbol(cls) + self.sep_index = self.add_symbol(sep) + self.nspecial = len(self.symbols) + + def cls(self): + """Helper to get index of cls symbol""" + return self.cls_index + + def sep(self): + """Helper to get index of sep symbol""" + return self.sep_index diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/list_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/list_dataset.py new file mode 100644 index 00000000..12f00aa4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/list_dataset.py @@ -0,0 +1,32 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from . import BaseWrapperDataset + + +class ListDataset(BaseWrapperDataset): + def __init__(self, dataset, sizes=None): + super().__init__(dataset) + self._sizes = sizes + + def __iter__(self): + for x in self.dataset: + yield x + + def collater(self, samples): + return samples + + @property + def sizes(self): + return self._sizes + + def num_tokens(self, index): + return self.sizes[index] + + def size(self, index): + return self.sizes[index] + + def set_epoch(self, epoch): + pass diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/lm_context_window_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/lm_context_window_dataset.py new file mode 100644 index 00000000..1a945927 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/lm_context_window_dataset.py @@ -0,0 +1,97 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch +from typing import Dict + +from fairseq.data.monolingual_dataset import MonolingualDataset + +from . import FairseqDataset + + +class LMContextWindowDataset(FairseqDataset): + """ + Wraps a MonolingualDataset and provides more context for evaluation. + + Each item in the new dataset will have a maximum size of + ``tokens_per_sample + context_window``. + + Args: + dataset: dataset to wrap + tokens_per_sample (int): the max number of tokens in each dataset item + context_window (int): the number of accumulated tokens to add to each + dataset item + pad_idx (int): padding symbol + """ + + def __init__( + self, + dataset: MonolingualDataset, + tokens_per_sample: int, + context_window: int, + pad_idx: int, + ): + assert context_window > 0 + self.dataset = dataset + self.tokens_per_sample = tokens_per_sample + self.context_window = context_window + self.pad_idx = pad_idx + self.prev_tokens = np.empty([0]) + + def __getitem__(self, index): + return self.dataset[index] + + def __len__(self): + return len(self.dataset) + + def collater(self, samples) -> Dict: + sample = self.dataset.collater(samples) + + pad = self.pad_idx + max_sample_len = self.tokens_per_sample + self.context_window + + bsz, tsz = sample["net_input"]["src_tokens"].shape + start_idxs = [0] * bsz + toks = sample["net_input"]["src_tokens"] + lengths = sample["net_input"]["src_lengths"] + tgt = sample["target"] + new_toks = np.empty([bsz, tsz + self.context_window], dtype=np.int64) + new_tgt = np.full([bsz, tsz + self.context_window], pad, dtype=np.int64) + sample_lens = toks.ne(pad).long().sum(dim=1).cpu() + for i in range(bsz): + sample_len = sample_lens[i] + extra = len(self.prev_tokens) + sample_len - max_sample_len + if extra > 0: + self.prev_tokens = self.prev_tokens[extra:] + pads = np.full(self.context_window - len(self.prev_tokens), pad) + new_toks[i] = np.concatenate([self.prev_tokens, toks[i].numpy(), pads]) + new_tgt[ + i, len(self.prev_tokens) : len(self.prev_tokens) + len(tgt[i]) + ] = tgt[i] + start_idxs[i] = len(self.prev_tokens) + lengths[i] += len(self.prev_tokens) + self.prev_tokens = new_toks[i][new_toks[i] != pad][-self.context_window :] + sample["net_input"]["src_tokens"] = torch.from_numpy(new_toks) + sample["target"] = torch.from_numpy(new_tgt) + sample["start_indices"] = start_idxs + return sample + + def num_tokens(self, index): + return self.dataset.num_tokens(index) + + def size(self, index): + return self.dataset.size(index) + + def ordered_indices(self): + # NOTE we don't shuffle the data to retain access to the previous dataset elements + return np.arange(len(self.dataset)) + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def prefetch(self, indices): + return self.dataset.prefetch(indices) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/lru_cache_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/lru_cache_dataset.py new file mode 100644 index 00000000..a7854ac1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/lru_cache_dataset.py @@ -0,0 +1,21 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from functools import lru_cache + +from . import BaseWrapperDataset + + +class LRUCacheDataset(BaseWrapperDataset): + def __init__(self, dataset, token=None): + super().__init__(dataset) + + @lru_cache(maxsize=8) + def __getitem__(self, index): + return self.dataset[index] + + @lru_cache(maxsize=8) + def collater(self, samples): + return self.dataset.collater(samples) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/mask_tokens_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/mask_tokens_dataset.py new file mode 100644 index 00000000..91232355 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/mask_tokens_dataset.py @@ -0,0 +1,220 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from functools import lru_cache + +import numpy as np +import torch +from fairseq.data import Dictionary, data_utils + +from . import BaseWrapperDataset, LRUCacheDataset + + +class MaskTokensDataset(BaseWrapperDataset): + """ + A wrapper Dataset for masked language modeling. + + Input items are masked according to the specified masking probability. + + Args: + dataset: Dataset to wrap. + sizes: Sentence lengths + vocab: Dictionary with the vocabulary and special tokens. + pad_idx: Id of pad token in vocab + mask_idx: Id of mask token in vocab + return_masked_tokens: controls whether to return the non-masked tokens + (the default) or to return a tensor with the original masked token + IDs (and *pad_idx* elsewhere). The latter is useful as targets for + masked LM training. + seed: Seed for random number generator for reproducibility. + mask_prob: probability of replacing a token with *mask_idx*. + leave_unmasked_prob: probability that a masked token is unmasked. + random_token_prob: probability of replacing a masked token with a + random token from the vocabulary. + freq_weighted_replacement: sample random replacement words based on + word frequencies in the vocab. + mask_whole_words: only mask whole words. This should be a byte mask + over vocab indices, indicating whether it is the beginning of a + word. We will extend any mask to encompass the whole word. + bpe: BPE to use for whole-word masking. + mask_multiple_length : repeat each mask index multiple times. Default + value is 1. + mask_stdev : standard deviation of masks distribution in case of + multiple masking. Default value is 0. + """ + + @classmethod + def apply_mask(cls, dataset: torch.utils.data.Dataset, *args, **kwargs): + """Return the source and target datasets for masked LM training.""" + dataset = LRUCacheDataset(dataset) + return ( + LRUCacheDataset(cls(dataset, *args, **kwargs, return_masked_tokens=False)), + LRUCacheDataset(cls(dataset, *args, **kwargs, return_masked_tokens=True)), + ) + + def __init__( + self, + dataset: torch.utils.data.Dataset, + vocab: Dictionary, + pad_idx: int, + mask_idx: int, + return_masked_tokens: bool = False, + seed: int = 1, + mask_prob: float = 0.15, + leave_unmasked_prob: float = 0.1, + random_token_prob: float = 0.1, + freq_weighted_replacement: bool = False, + mask_whole_words: torch.Tensor = None, + mask_multiple_length: int = 1, + mask_stdev: float = 0.0, + ): + assert 0.0 < mask_prob < 1.0 + assert 0.0 <= random_token_prob <= 1.0 + assert 0.0 <= leave_unmasked_prob <= 1.0 + assert random_token_prob + leave_unmasked_prob <= 1.0 + assert mask_multiple_length >= 1 + assert mask_stdev >= 0.0 + + self.dataset = dataset + self.vocab = vocab + self.pad_idx = pad_idx + self.mask_idx = mask_idx + self.return_masked_tokens = return_masked_tokens + self.seed = seed + self.mask_prob = mask_prob + self.leave_unmasked_prob = leave_unmasked_prob + self.random_token_prob = random_token_prob + self.mask_whole_words = mask_whole_words + self.mask_multiple_length = mask_multiple_length + self.mask_stdev = mask_stdev + + if random_token_prob > 0.0: + if freq_weighted_replacement: + weights = np.array(self.vocab.count) + else: + weights = np.ones(len(self.vocab)) + weights[: self.vocab.nspecial] = 0 + self.weights = weights / weights.sum() + + self.epoch = 0 + + @property + def can_reuse_epoch_itr_across_epochs(self): + return True # only the noise changes, not item sizes + + def set_epoch(self, epoch, **unused): + super().set_epoch(epoch) + self.epoch = epoch + + def __getitem__(self, index: int): + return self.__getitem_cached__(self.seed, self.epoch, index) + + @lru_cache(maxsize=8) + def __getitem_cached__(self, seed: int, epoch: int, index: int): + with data_utils.numpy_seed(self.seed, self.epoch, index): + item = self.dataset[index] + sz = len(item) + + assert ( + self.mask_idx not in item + ), "Dataset contains mask_idx (={}), this is not expected!".format( + self.mask_idx, + ) + + if self.mask_whole_words is not None: + word_begins_mask = self.mask_whole_words.gather(0, item) + word_begins_idx = word_begins_mask.nonzero().view(-1) + sz = len(word_begins_idx) + words = np.split(word_begins_mask, word_begins_idx)[1:] + assert len(words) == sz + word_lens = list(map(len, words)) + + # decide elements to mask + mask = np.full(sz, False) + num_mask = int( + # add a random number for probabilistic rounding + self.mask_prob * sz / float(self.mask_multiple_length) + + np.random.rand() + ) + + # multiple masking as described in the vq-wav2vec paper (https://arxiv.org/abs/1910.05453) + mask_idc = np.random.choice(sz, num_mask, replace=False) + if self.mask_stdev > 0.0: + lengths = np.random.normal( + self.mask_multiple_length, self.mask_stdev, size=num_mask + ) + lengths = [max(0, int(round(x))) for x in lengths] + mask_idc = np.asarray( + [ + mask_idc[j] + offset + for j in range(len(mask_idc)) + for offset in range(lengths[j]) + ], + dtype=np.int64, + ) + else: + mask_idc = np.concatenate( + [mask_idc + i for i in range(self.mask_multiple_length)] + ) + mask_idc = mask_idc[mask_idc < len(mask)] + try: + mask[mask_idc] = True + except: # something wrong + print( + "Assigning mask indexes {} to mask {} failed!".format( + mask_idc, mask + ) + ) + raise + + if self.return_masked_tokens: + # exit early if we're just returning the masked tokens + # (i.e., the targets for masked LM training) + if self.mask_whole_words is not None: + mask = np.repeat(mask, word_lens) + new_item = np.full(len(mask), self.pad_idx) + new_item[mask] = item[torch.from_numpy(mask.astype(np.uint8)) == 1] + return torch.from_numpy(new_item) + + # decide unmasking and random replacement + rand_or_unmask_prob = self.random_token_prob + self.leave_unmasked_prob + if rand_or_unmask_prob > 0.0: + rand_or_unmask = mask & (np.random.rand(sz) < rand_or_unmask_prob) + if self.random_token_prob == 0.0: + unmask = rand_or_unmask + rand_mask = None + elif self.leave_unmasked_prob == 0.0: + unmask = None + rand_mask = rand_or_unmask + else: + unmask_prob = self.leave_unmasked_prob / rand_or_unmask_prob + decision = np.random.rand(sz) < unmask_prob + unmask = rand_or_unmask & decision + rand_mask = rand_or_unmask & (~decision) + else: + unmask = rand_mask = None + + if unmask is not None: + mask = mask ^ unmask + + if self.mask_whole_words is not None: + mask = np.repeat(mask, word_lens) + + new_item = np.copy(item) + new_item[mask] = self.mask_idx + if rand_mask is not None: + num_rand = rand_mask.sum() + if num_rand > 0: + if self.mask_whole_words is not None: + rand_mask = np.repeat(rand_mask, word_lens) + num_rand = rand_mask.sum() + + new_item[rand_mask] = np.random.choice( + len(self.vocab), + num_rand, + p=self.weights, + ) + + return torch.from_numpy(new_item) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/monolingual_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/monolingual_dataset.py new file mode 100644 index 00000000..54fd583b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/monolingual_dataset.py @@ -0,0 +1,253 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch + +from . import FairseqDataset, data_utils + + +def collate(samples, pad_idx, eos_idx, fixed_pad_length=None, pad_to_bsz=None): + if len(samples) == 0: + return {} + + def merge(key, is_list=False): + if is_list: + res = [] + for i in range(len(samples[0][key])): + res.append( + data_utils.collate_tokens( + [s[key][i] for s in samples], + pad_idx, + eos_idx, + left_pad=False, + pad_to_length=fixed_pad_length, + pad_to_bsz=pad_to_bsz, + ) + ) + return res + else: + return data_utils.collate_tokens( + [s[key] for s in samples], + pad_idx, + eos_idx, + left_pad=False, + pad_to_length=fixed_pad_length, + pad_to_bsz=pad_to_bsz, + ) + + src_tokens = merge("source") + if samples[0]["target"] is not None: + is_target_list = isinstance(samples[0]["target"], list) + target = merge("target", is_target_list) + else: + target = src_tokens + + return { + "id": torch.LongTensor([s["id"] for s in samples]), + "nsentences": len(samples), + "ntokens": sum(len(s["source"]) for s in samples), + "net_input": { + "src_tokens": src_tokens, + "src_lengths": torch.LongTensor([s["source"].numel() for s in samples]), + }, + "target": target, + } + + +class MonolingualDataset(FairseqDataset): + """ + A wrapper around torch.utils.data.Dataset for monolingual data. + + Args: + dataset (torch.utils.data.Dataset): dataset to wrap + sizes (List[int]): sentence lengths + vocab (~fairseq.data.Dictionary): vocabulary + shuffle (bool, optional): shuffle the elements before batching + (default: True). + """ + + def __init__( + self, + dataset, + sizes, + src_vocab, + tgt_vocab=None, + add_eos_for_other_targets=False, + shuffle=False, + targets=None, + add_bos_token=False, + fixed_pad_length=None, + pad_to_bsz=None, + src_lang_idx=None, + tgt_lang_idx=None, + ): + self.dataset = dataset + self.sizes = np.array(sizes) + self.vocab = src_vocab + self.tgt_vocab = tgt_vocab or src_vocab + self.add_eos_for_other_targets = add_eos_for_other_targets + self.shuffle = shuffle + self.add_bos_token = add_bos_token + self.fixed_pad_length = fixed_pad_length + self.pad_to_bsz = pad_to_bsz + self.src_lang_idx = src_lang_idx + self.tgt_lang_idx = tgt_lang_idx + + assert targets is None or all( + t in {"self", "future", "past"} for t in targets + ), "targets must be none or one of 'self', 'future', 'past'" + if targets is not None and len(targets) == 0: + targets = None + self.targets = targets + + def __getitem__(self, index): + if self.targets is not None: + # *future_target* is the original sentence + # *source* is shifted right by 1 (maybe left-padded with eos) + # *past_target* is shifted right by 2 (left-padded as needed) + # + # Left-to-right language models should condition on *source* and + # predict *future_target*. + # Right-to-left language models should condition on *source* and + # predict *past_target*. + source, future_target, past_target = self.dataset[index] + source, target = self._make_source_target( + source, future_target, past_target + ) + else: + source = self.dataset[index] + target = None + source, target = self._maybe_add_bos(source, target) + return {"id": index, "source": source, "target": target} + + def __len__(self): + return len(self.dataset) + + def _make_source_target(self, source, future_target, past_target): + if self.targets is not None: + target = [] + + if ( + self.add_eos_for_other_targets + and (("self" in self.targets) or ("past" in self.targets)) + and source[-1] != self.vocab.eos() + ): + # append eos at the end of source + source = torch.cat([source, source.new([self.vocab.eos()])]) + + if "future" in self.targets: + future_target = torch.cat( + [future_target, future_target.new([self.vocab.pad()])] + ) + if "past" in self.targets: + # first token is before the start of sentence which is only used in "none" break mode when + # add_eos_for_other_targets is False + past_target = torch.cat( + [ + past_target.new([self.vocab.pad()]), + past_target[1:], + source[-2, None], + ] + ) + + for t in self.targets: + if t == "self": + target.append(source) + elif t == "future": + target.append(future_target) + elif t == "past": + target.append(past_target) + else: + raise Exception("invalid target " + t) + + if len(target) == 1: + target = target[0] + else: + target = future_target + + return source, self._filter_vocab(target) + + def _maybe_add_bos(self, source, target): + if self.add_bos_token: + source = torch.cat([source.new([self.vocab.bos()]), source]) + if target is not None: + target = torch.cat([target.new([self.tgt_vocab.bos()]), target]) + return source, target + + def num_tokens_vec(self, indices): + """Return the number of tokens for a set of positions defined by indices. + This value is used to enforce ``--max-tokens`` during batching.""" + return self.sizes[indices] + + def _filter_vocab(self, target): + if len(self.tgt_vocab) != len(self.vocab): + + def _filter(target): + mask = target.ge(len(self.tgt_vocab)) + if mask.any(): + target[mask] = self.tgt_vocab.unk() + return target + + if isinstance(target, list): + return [_filter(t) for t in target] + return _filter(target) + return target + + def collater(self, samples): + """Merge a list of samples to form a mini-batch. + + Args: + samples (List[dict]): samples to collate + + Returns: + dict: a mini-batch with the following keys: + + - `id` (LongTensor): example IDs in the original input order + - `ntokens` (int): total number of tokens in the batch + - `net_input` (dict): the input to the Model, containing keys: + + - `src_tokens` (LongTensor): a padded 2D Tensor of tokens in + the source sentence of shape `(bsz, src_len)`. Padding will + appear on the right. + + - `target` (LongTensor): a padded 2D Tensor of tokens in the + target sentence of shape `(bsz, tgt_len)`. Padding will appear + on the right. + """ + return collate( + samples, + self.vocab.pad(), + self.vocab.eos(), + self.fixed_pad_length, + self.pad_to_bsz, + ) + + def num_tokens(self, index): + """Return the number of tokens in a sample. This value is used to + enforce ``--max-tokens`` during batching.""" + return self.sizes[index] + + def size(self, index): + """Return an example's size as a float or tuple. This value is used when + filtering a dataset with ``--max-positions``.""" + return self.sizes[index] + + def ordered_indices(self): + """Return an ordered list of indices. Batches will be constructed based + on this order.""" + if self.shuffle: + order = [np.random.permutation(len(self))] + else: + order = [np.arange(len(self))] + order.append(self.sizes) + return np.lexsort(order) + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def prefetch(self, indices): + self.dataset.prefetch(indices) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/multi_corpus_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/multi_corpus_dataset.py new file mode 100644 index 00000000..a3f47c72 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/multi_corpus_dataset.py @@ -0,0 +1,256 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import time +from collections import OrderedDict +from typing import Dict, List, Optional + +import numpy as np +from fairseq.data import data_utils + +from . import FairseqDataset + +logger = logging.getLogger(__name__) + + +class MultiCorpusDataset(FairseqDataset): + """ + Stores multiple instances of FairseqDataset together. + Unless batch_sample=True, requires each instance + to be the same dataset, as the collate method needs to work on batches with + samples from each dataset. + + Allows specifying a distribution over the datasets to use. Note that unlike + MultiCorpusSampledDataset, this distribution allows sampling for each item, + rather than on a batch level. Note that datasets with sampling probabilty + of 0 will be skipped. + + Each time ordered_indices() is called, a new sample is generated with + the specified distribution. + + Args: + datasets: a OrderedDict of FairseqDataset instances. + distribution: a List containing the probability of getting an utterance from + corresponding dataset + seed: random seed for sampling the datsets + sort_indices: if true, will sort the ordered indices by size + batch_sample: if true, will ensure each batch is from a single dataset + """ + + def __init__( + self, + datasets: Dict[str, FairseqDataset], + distribution: List[float], + seed: int, + sort_indices: bool = False, + batch_sample: bool = False, + distributed_rank: Optional[int] = None, + ): + super().__init__() + assert isinstance(datasets, OrderedDict) + assert len(datasets) == len(distribution) + assert sum(distribution) == 1 + self.datasets = datasets + self.distribution = distribution + self.seed = seed + self.sort_indices = sort_indices + self.batch_sample = batch_sample + self.distributed_rank = distributed_rank + + # Avoid repeated conversions to list later + self.dataset_list = list(datasets.values()) + self.total_num_instances = 0 + + first_dataset = self.dataset_list[0] + + self.num_instances_per_dataset = [] + self.dataset_offsets = [] + for i, dataset in enumerate(self.dataset_list): + assert isinstance(dataset, FairseqDataset) + assert type(dataset) is type(first_dataset) + self.num_instances_per_dataset.append( + 0 if self.distribution[i] == 0 else len(dataset) + ) + self.dataset_offsets.append(self.total_num_instances) + self.total_num_instances += self.num_instances_per_dataset[i] + + def ordered_indices(self): + start = time.time() + with data_utils.numpy_seed(self.seed, self.epoch): + logger.info( + f"sampling new dataset with seed {self.seed} epoch {self.epoch}" + ) + sampled_indices = [] + num_selected_instances = 0 + + # For each dataset i, sample self.distribution[i] * self.total_num_instances + for i, key in enumerate(self.datasets): + if self.distribution[i] == 0: + # skip dataset if sampling probability is 0 + continue + + if i < len(self.datasets) - 1: + num_instances = int(self.distribution[i] * self.total_num_instances) + high = self.dataset_offsets[i + 1] + else: + num_instances = self.total_num_instances - num_selected_instances + high = self.total_num_instances + + logger.info(f"sampling {num_instances} from {key} dataset") + num_selected_instances += num_instances + + # First, add k copies of the dataset where k = num_instances // len(dataset). + # This ensures an equal distribution of the data points as much as possible. + # For the remaining entries randomly sample them + dataset_size = len(self.datasets[key]) + num_copies = num_instances // dataset_size + dataset_indices = ( + np.random.permutation(high - self.dataset_offsets[i]) + + self.dataset_offsets[i] + )[: num_instances - num_copies * dataset_size] + if num_copies > 0: + sampled_indices += list( + np.concatenate( + ( + np.repeat( + np.arange(self.dataset_offsets[i], high), num_copies + ), + dataset_indices, + ) + ) + ) + else: + sampled_indices += list(dataset_indices) + + assert ( + len(sampled_indices) == self.total_num_instances + ), f"{len(sampled_indices)} vs {self.total_num_instances}" + + np.random.shuffle(sampled_indices) + if self.sort_indices: + sampled_indices.sort(key=lambda i: self.num_tokens(i)) + + logger.info( + "multi_corpus_dataset ordered_indices took {}s".format( + time.time() - start + ) + ) + return np.array(sampled_indices, dtype=np.int64) + + def _map_index(self, index: int): + """ + If dataset A has length N and dataset B has length M + then index 1 maps to index 1 of dataset A, and index N + 1 + maps to index 1 of B. + """ + counter = 0 + for num_instances, key in zip(self.num_instances_per_dataset, self.datasets): + if index < counter + num_instances: + return index - counter, key + counter += num_instances + raise ValueError( + "Invalid index: {}, max: {}".format(index, self.total_num_instances) + ) + + def __len__(self): + """ + Length of this dataset is the sum of individual datasets + """ + return self.total_num_instances + + def __getitem__(self, index): + new_index, key = self._map_index(index) + try: + item = self.datasets[key][new_index] + item["full_id"] = index + return item + except Exception as e: + e.args = (f"Error from {key} dataset", *e.args) + raise + + def collater(self, samples): + """ + If we are doing batch sampling, then pick the right collater to use. + + Otherwise we assume all collaters are the same. + """ + if len(samples) == 0: + return None + if "full_id" in samples[0]: + _, key = self._map_index(samples[0]["full_id"]) + try: + batch = self.datasets[key].collater(samples) + except Exception: + print(f"Collating failed for key {key}", flush=True) + raise + return batch + else: + # Subclasses may override __getitem__ to not specify full_id + return list(self.datasets.values())[0].collater(samples) + + def num_tokens(self, index: int): + index, key = self._map_index(index) + return self.datasets[key].num_tokens(index) + + def size(self, index: int): + index, key = self._map_index(index) + return self.datasets[key].size(index) + + @property + def can_reuse_epoch_itr_across_epochs(self): + return False + + def set_epoch(self, epoch, **unused): + super().set_epoch(epoch) + logger.info(f"setting epoch of multi_corpus_dataset to {epoch}") + self.epoch = epoch + + @property + def supports_prefetch(self): + return False + + @property + def supports_fetch_outside_dataloader(self): + return all( + self.datasets[key].supports_fetch_outside_dataloader + for key in self.datasets + ) + + def batch_by_size( + self, + indices, + max_tokens=None, + max_sentences=None, + required_batch_size_multiple=1, + ): + if not self.batch_sample: + return super().batch_by_size( + indices, max_tokens, max_sentences, required_batch_size_multiple + ) + + dataset_indices = {key: [] for key in self.datasets} + for i in indices: + _, key = self._map_index(i) + dataset_indices[key].append(i) + + batches = [] + for key in dataset_indices: + cur_batches = super().batch_by_size( + np.array(dataset_indices[key], dtype=np.int64), + max_tokens, + max_sentences, + required_batch_size_multiple, + ) + logger.info(f"Created {len(cur_batches)} batches for dataset {key}") + batches += cur_batches + + # If this dataset is used in a distributed training setup, + # then shuffle such that the order is seeded by the distributed rank + # as well + if self.distributed_rank is not None: + with data_utils.numpy_seed(self.seed, self.epoch, self.distributed_rank): + np.random.shuffle(batches) + return batches diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/multi_corpus_sampled_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/multi_corpus_sampled_dataset.py new file mode 100644 index 00000000..e2e9fdf0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/multi_corpus_sampled_dataset.py @@ -0,0 +1,152 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections import OrderedDict +from typing import Callable, Dict, List + +import numpy as np + +from . import FairseqDataset + + +def uniform_sampler(x): + # Sample from uniform distribution + return np.random.choice(x, 1).item() + + +class MultiCorpusSampledDataset(FairseqDataset): + """ + Stores multiple instances of FairseqDataset together and in every iteration + creates a batch by first sampling a dataset according to a specified + probability distribution and then getting instances from that dataset. + + Args: + datasets: an OrderedDict of FairseqDataset instances. + sampling_func: A function for sampling over list of dataset keys. + The default strategy is to sample uniformly. + """ + + def __init__( + self, + datasets: Dict[str, FairseqDataset], + sampling_func: Callable[[List], int] = None, + ): + super().__init__() + assert isinstance(datasets, OrderedDict) + self.datasets = datasets + if sampling_func is None: + sampling_func = uniform_sampler + self.sampling_func = sampling_func + + self.total_num_instances = 0 + for _, dataset in datasets.items(): + assert isinstance(dataset, FairseqDataset) + self.total_num_instances += len(dataset) + + self._ordered_indices = None + + def __len__(self): + """ + Length of this dataset is the sum of individual datasets + """ + return self.total_num_instances + + def ordered_indices(self): + """ + Ordered indices for batching. Here we call the underlying + dataset's ordered_indices() so that we get the same random ordering + as we would have from using the underlying dataset directly. + """ + if self._ordered_indices is None: + self._ordered_indices = OrderedDict( + [ + (key, dataset.ordered_indices()) + for key, dataset in self.datasets.items() + ] + ) + return np.arange(len(self)) + + def _map_index_to_dataset(self, key: int, index: int): + """ + Different underlying datasets have different lengths. In order to ensure + we are not accessing an index outside the range of the current dataset + size, we wrap around. This function should be called after we have + created an ordering for this and all underlying datasets. + """ + assert ( + self._ordered_indices is not None + ), "Must call MultiCorpusSampledDataset.ordered_indices() first" + mapped_index = index % len(self.datasets[key]) + return self._ordered_indices[key][mapped_index] + + def __getitem__(self, index: int): + """ + Get the item associated with index from each underlying dataset. + Since index is in the range of [0, TotalNumInstances], we need to + map the index to the dataset before retrieving the item. + """ + return OrderedDict( + [ + (key, dataset[self._map_index_to_dataset(key, index)]) + for key, dataset in self.datasets.items() + ] + ) + + def collater(self, samples: List[Dict]): + """ + Generate a mini-batch for this dataset. + To convert this into a regular mini-batch we use the following + logic: + 1. Select a dataset using the specified probability distribution. + 2. Call the collater function of the selected dataset. + """ + if len(samples) == 0: + return None + + selected_key = self.sampling_func(list(self.datasets.keys())) + selected_samples = [sample[selected_key] for sample in samples] + return self.datasets[selected_key].collater(selected_samples) + + def num_tokens(self, index: int): + """ + Return an example's length (number of tokens), used for batching. Here + we return the max across all examples at index across all underlying + datasets. + """ + return max( + dataset.num_tokens(self._map_index_to_dataset(key, index)) + for key, dataset in self.datasets.items() + ) + + def size(self, index: int): + """ + Return an example's size as a float or tuple. Here we return the max + across all underlying datasets. This value is used when filtering a + dataset with max-positions. + """ + return max( + dataset.size(self._map_index_to_dataset(key, index)) + for key, dataset in self.datasets.items() + ) + + @property + def supports_prefetch(self): + return all( + getattr(dataset, "supports_prefetch", False) + for dataset in self.datasets.values() + ) + + def prefetch(self, indices): + for key, dataset in self.datasets.items(): + dataset.prefetch( + [self._map_index_to_dataset(key, index) for index in indices] + ) + + @property + def supports_fetch_outside_dataloader(self): + return all( + self.datasets[key].supports_fetch_outside_dataloader + for key in self.datasets + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/__init__.py new file mode 100644 index 00000000..62642369 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/__init__.py @@ -0,0 +1,4 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/multilingual_data_manager.py b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/multilingual_data_manager.py new file mode 100644 index 00000000..876dfcec --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/multilingual_data_manager.py @@ -0,0 +1,1156 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import itertools +import json +import logging +import math +import os +from collections import OrderedDict, defaultdict +from argparse import ArgumentError + +from fairseq import utils +from fairseq.data import ( + AppendTokenDataset, + ConcatDataset, + Dictionary, + LanguagePairDataset, + PrependTokenDataset, + SampledMultiDataset, + SampledMultiEpochDataset, + StripTokenDataset, + TransformEosLangPairDataset, + TruncateDataset, + data_utils, + indexed_dataset, +) +from fairseq.data.multilingual.multilingual_utils import ( + EncoderLangtok, + LangTokSpec, + LangTokStyle, + augment_dictionary, + get_lang_tok, +) +from fairseq.data.multilingual.sampled_multi_dataset import CollateFormat +from fairseq.file_io import PathManager +from fairseq.utils import FileContentsAction, csv_str_list, eval_str_dict + + +logger = logging.getLogger(__name__) + +SRC_DICT_NAME = "src" +TGT_DICT_NAME = "tgt" + + +def _lang_id(dic: Dictionary, lang: str): + """Return language ID index.""" + idx = dic.index(lang) + assert idx != dic.unk_index, "cannot find language ID for lang {}".format(lang) + return idx + + +def load_sampling_weights(from_file): + with open(from_file) as f: + weights = json.load(f) + return weights + + +class MultilingualDatasetManager(object): + def __init__(self, args, lang_pairs, langs, dicts, sampling_method): + super().__init__() + self.args = args + self.seed = args.seed + self.lang_pairs = lang_pairs + self.extra_lang_pairs = ( + list({p for _, v in args.extra_lang_pairs.items() for p in v.split(",")}) + if args.extra_lang_pairs + else [] + ) + self.src_langs = { + p.split("-")[0] for p in args.lang_pairs + self.extra_lang_pairs + } + self.tgt_langs = { + p.split("-")[1] for p in args.lang_pairs + self.extra_lang_pairs + } + self.langs = langs + self.dicts = dicts + self.lang_dict = self.create_lang_dictionary(self.langs) + self.sampling_method = sampling_method + self.sampling_scheduler = None + self._has_sharded_data = False + self._num_shards_dict = {} + self._training_data_sizes = defaultdict(lambda: {}) + + @classmethod + def setup_data_manager(cls, args, lang_pairs, langs, dicts, sampling_method): + return MultilingualDatasetManager( + args, lang_pairs, langs, dicts, sampling_method + ) + + @staticmethod + def add_args(parser): + parser.add_argument( + "data", + help="colon separated path to data directories list, \ + will be iterated upon during epochs in round-robin manner", + action=FileContentsAction, + ) + parser.add_argument( + "--langs", + default=None, + type=csv_str_list, + help="a list of languages comma sperated languages which can appear in lang-pairs; " + "note that the ordering determines language token IDs", + ) + parser.add_argument( + "--lang-dict", + default=None, + type=str, + help="an external file which contains a list of " + "languages which can appear in lang-pairs; " + "note that the ordering determines language token IDs; " + "--langs and --lang-dict are two exclusive options", + ) + parser.add_argument( + "--source-dict", + default=None, + type=str, + help="path to source dictionary; if specified it will override per language dictionary loading", + ) + parser.add_argument( + "--target-dict", + default=None, + type=str, + help="path to target dictionary; if specified it will override per language dictionary loading", + ) + parser.add_argument( + "--lang-tok-style", + default=LangTokStyle.multilingual.value, + type=str, + choices=[LangTokStyle.multilingual.value, LangTokStyle.mbart.value], + help="language token styles", + ) + + parser.add_argument( + "--load-alignments", + action="store_true", + help="load the binarized alignments", + ) + parser.add_argument( + "--left-pad-source", + default="True", + type=str, + metavar="BOOL", + help="pad the source on the left", + ) + parser.add_argument( + "--left-pad-target", + default="False", + type=str, + metavar="BOOL", + help="pad the target on the left", + ) + try: + parser.add_argument( + "--max-source-positions", + default=1024, + type=int, + metavar="N", + help="max number of tokens in the source sequence", + ) + parser.add_argument( + "--max-target-positions", + default=1024, + type=int, + metavar="N", + help="max number of tokens in the target sequence", + ) + except ArgumentError: + # this might have already been defined. Once we transition this to hydra it should be fine to add it here. + pass + parser.add_argument( + "--upsample-primary", + default=1, + type=int, + help="amount to upsample primary dataset", + ) + parser.add_argument( + "--truncate-source", + action="store_true", + default=False, + help="truncate source to max-source-positions", + ) + parser.add_argument( + "--encoder-langtok", + default=None, + type=str, + choices=[EncoderLangtok.src.value, EncoderLangtok.tgt.value], + metavar="SRCTGT", + help="prepend to the beginning of source sentence the source or target " + "language token. (src/tgt)", + ) + parser.add_argument( + "--decoder-langtok", + action="store_true", + help="prepend to the beginning of target sentence the target language token", + ) + parser.add_argument( + "--lang-tok-replacing-bos-eos", action="store_true", default=False + ) + parser.add_argument( + "--enable-lang-ids", + default=False, + action="store_true", + help="whether to include language IDs in samples", + ) + parser.add_argument( + "--enable-reservsed-directions-shared-datasets", + default=False, + action="store_true", + help="whether to allow datasets be used in reversed directions", + ) + + parser.add_argument( + "--extra-data", + help='a dictionary of data name to this path, \ + e.g. {"mined", path_to_mined_data, "denoised": path_to_denoised_data}', + type=lambda uf: eval_str_dict(uf, type=str), + default=None, + ) + parser.add_argument( + "--extra-lang-pairs", + help='a dictionary of data name to the language pairs they serve, \ + e.g. {"mined": comma-separated-lang-pairs, "denoised": comma-separated-lang-pairs}', + type=lambda uf: eval_str_dict(uf, type=str), + default=None, + ) + parser.add_argument( + "--fixed-dictionary", + help="Fixed dictionary to use with model path", + default=None, + type=str, + ) + parser.add_argument( + "--langtoks-specs", + help='a list of comma separated data types that a set of language tokens to be specialized for, \ + e.g. "main,dae,mined". There will be a set of language tokens added to the vocab to \ + distinguish languages in different training data types. If not specified, default language \ + tokens per languages will be added', + default=LangTokSpec.main.value, + type=csv_str_list, + ) + parser.add_argument( + "--langtoks", + help='a dictionary of how to add language tokens, \ + e.g. {"mined": (None, "tgt"), "mono_dae": ("src.dae", "tgt"), "main": \ + ("src", "tgt")}, or {"mined": ("src.mined", "tgt")}', + default=None, + type=lambda uf: eval_str_dict(uf, type=str), + ) + parser.add_argument( + "--sampling-weights-from-file", + help='a file contain a python dictionary of how to sample data sets, \ + e.g. { "main:en_XX-es_XX": 0.2, "mined:en_XX-pt_XX": 0.5, \ + "mono_dae:es_XX-es_XX: 0.3, "main:en_xx-fr_XX": 0.8 }', + default=None, + type=str, + ) + parser.add_argument( + "--sampling-weights", + help='a dictionary of how to sample data sets, \ + e.g. { "main:en_XX-es_XX": 0.2, "mined:en_XX-pt_XX": 0.5, \ + "mono_dae:es_XX-es_XX: 0.3, "main:en_xx-fr_XX": 0.8 }', + default=None, + type=lambda uf: eval_str_dict(uf, type=str), + ) + parser.add_argument( + "--virtual-epoch-size", + default=None, + type=int, + help="virtual epoch size to speed up data loading", + ) + parser.add_argument( + "--virtual-data-size", + default=None, + type=int, + help="virtual data size of the whole joint dataset to speed" + "up data loading and have specific dynamic sampling strategy interval", + ) + + @classmethod + def load_langs(cls, args, **kwargs): + if args.lang_dict and args.langs: + raise ValueError("--langs and --lang-dict can not both be specified") + if args.lang_dict is None and args.langs is None: + logger.warning( + "External language dictionary is not provided; " + "use lang-pairs to infer the set of supported languages. " + "The language ordering is not stable which might cause " + "misalignment in pretraining and finetuning." + ) + # infer from lang_pairs as it is + langs = list( + {x for lang_pair in args.lang_pairs for x in lang_pair.split("-")} + ) + langs = sorted(langs) + logger.info(f"inferred language list: {langs}") + elif args.lang_dict: + with open( + PathManager.get_local_path(args.lang_dict), "r", encoding="utf-8" + ) as f: + langs = [lang.strip() for lang in f.readlines() if lang.strip()] + logger.info( + f"loaded language list from {args.lang_dict} as they are ordered in file" + ) + elif args.langs: + langs = args.langs + logger.info( + f"parsed the language list as they are ordered in the option: {langs}" + ) + return langs + + def has_sharded_data(self, split): + return self._has_sharded_data and split == getattr( + self.args, "train_subset", None + ) + + def _shared_collater(self): + return not (self.args.extra_data and "mono_dae" in self.args.extra_data) and ( + not self.args.lang_tok_replacing_bos_eos + ) + + def estimate_global_pass_epoch(self, epoch): + if self.args.virtual_epoch_size is None or self.args.virtual_data_size is None: + return None + # one epoch more for remaining data in each shard + virtual_epochs_per_shard = math.ceil( + self.args.virtual_data_size / self.args.virtual_epoch_size + ) + # note that fairseq epoch / shard_epoch starts from 1 + shard_epoch = (epoch - 1) // virtual_epochs_per_shard + 1 + return shard_epoch + + @classmethod + def prepare(cls, load_dictionary, args, **kargs): + args.left_pad_source = utils.eval_bool(args.left_pad_source) + args.left_pad_target = utils.eval_bool(args.left_pad_target) + + if not hasattr(args, "shuffle_instance"): + args.shuffle_instance = False + if args.langtoks is None: + args.langtoks = {} + if "main" not in args.langtoks: + src_langtok_spec = args.encoder_langtok if args.encoder_langtok else None + tgt_langtok_spec = "tgt" if args.decoder_langtok else None + args.langtoks["main"] = (src_langtok_spec, tgt_langtok_spec) + + def check_langs(langs, pairs): + messages = [] + for src, tgt in pairs: + if src not in langs or tgt not in langs: + messages.append( + f"language pair {src}-{tgt} contains languages " + "that are not in the language dictionary" + ) + if len(messages) > 0: + raise ValueError(" ".join(messages) + f"; langs: {langs}") + + if args.lang_pairs is None: + raise ValueError( + "--lang-pairs is required. List all the language pairs in the training objective." + ) + if isinstance(args.lang_pairs, str): + args.lang_pairs = args.lang_pairs.split(",") + if args.source_lang is not None or args.target_lang is not None: + training = False + else: + training = True + language_list = cls.load_langs(args, **kargs) + check_langs( + language_list, + ( + [p.split("-") for p in args.lang_pairs] + if training + else [(args.source_lang, args.target_lang)] + ), + ) + + def load_dictionary_and_postproc(path): + d = load_dictionary(path) + augment_dictionary( + dictionary=d, + language_list=language_list, + lang_tok_style=args.lang_tok_style, + langtoks_specs=args.langtoks_specs, + extra_data=args.extra_data, + ) + return d + + dicts = cls.load_all_dictionaries( + args, language_list, load_dictionary_and_postproc, training + ) + return language_list, dicts, training + + @classmethod + def load_all_dictionaries(cls, args, language_list, load_dictionary, training): + dicts = OrderedDict() + if args.source_dict is not None: + dicts[SRC_DICT_NAME] = load_dictionary(args.source_dict) + if args.target_dict is not None: + dicts[TGT_DICT_NAME] = load_dictionary(args.target_dict) + + if training: + extra_lang_pairs = ( + list( + {p for _, v in args.extra_lang_pairs.items() for p in v.split(",")} + ) + if args.extra_lang_pairs + else [] + ) + src_langs_to_load_dicts = sorted( + {p.split("-")[0] for p in (args.lang_pairs + extra_lang_pairs)} + ) + tgt_langs_to_load_dicts = sorted( + {p.split("-")[1] for p in (args.lang_pairs + extra_lang_pairs)} + ) + else: + src_langs_to_load_dicts = [args.source_lang] + tgt_langs_to_load_dicts = [args.target_lang] + + paths = utils.split_paths(args.data) + assert len(paths) > 0 + + def load_dicts(langs_to_load_dicts): + for lang in langs_to_load_dicts: + dicts[lang] = load_dictionary( + os.path.join(paths[0], "dict.{}.txt".format(lang)) + ) + if len(dicts) > 0: + dict0 = next(iter(dicts.values())) + assert dicts[lang].pad() == dict0.pad() + assert dicts[lang].eos() == dict0.eos() + assert dicts[lang].unk() == dict0.unk() + logger.info("[{}] dictionary: {} types".format(lang, len(dicts[lang]))) + + if args.fixed_dictionary is not None: + fixed_dict = load_dictionary(args.fixed_dictionary) + dicts = { + lang: fixed_dict + for lang in src_langs_to_load_dicts + tgt_langs_to_load_dicts + } + else: + if args.source_dict is None: + load_dicts(src_langs_to_load_dicts) + if args.target_dict is None: + load_dicts(tgt_langs_to_load_dicts) + return dicts + + def get_source_dictionary(self, lang): + if self.args.source_dict is not None: + return self.dicts[SRC_DICT_NAME] + else: + return self.dicts[lang] + + def get_target_dictionary(self, lang): + if self.args.target_dict is not None: + return self.dicts[TGT_DICT_NAME] + else: + return self.dicts[lang] + + @classmethod + def create_lang_dictionary(cls, langs): + unk = "" + # hack to remove symbols other than unk as they are not needed by lang dict + lang_dict = Dictionary(pad=unk, eos=unk, unk=unk, bos=unk) + for lang in langs: + lang_dict.add_symbol(lang) + return lang_dict + + @classmethod + def get_langtok_index(cls, lang_tok, dic): + idx = dic.index(lang_tok) + assert ( + idx != dic.unk_index + ), "cannot find language token {} in the dictionary".format(lang_tok) + return idx + + def get_encoder_langtok(self, src_lang, tgt_lang, spec=None): + if spec is None: + return None + if spec and spec.startswith("src"): + if src_lang is None: + return None + langtok = get_lang_tok( + lang=src_lang, lang_tok_style=self.args.lang_tok_style, spec=spec + ) + else: + if tgt_lang is None: + return None + langtok = get_lang_tok( + lang=tgt_lang, lang_tok_style=self.args.lang_tok_style, spec=spec + ) + return self.get_langtok_index( + langtok, + self.get_source_dictionary(src_lang) + if src_lang + else self.get_target_dictionary(tgt_lang), + ) + + def get_decoder_langtok(self, tgt_lang, spec=None): + if spec is None: + return None + langtok = get_lang_tok( + lang=tgt_lang, lang_tok_style=self.args.lang_tok_style, spec=spec + ) + return self.get_langtok_index(langtok, self.get_target_dictionary(tgt_lang)) + + @classmethod + def load_data(cls, path, vdict, impl): + dataset = data_utils.load_indexed_dataset(path, vdict, impl) + return dataset + + @classmethod + def split_exists(cls, split, src, tgt, lang, data_path, dataset_impl): + filename = os.path.join(data_path, "{}.{}-{}.{}".format(split, src, tgt, lang)) + return indexed_dataset.dataset_exists(filename, impl=dataset_impl) + + def load_lang_dataset( + self, + data_path, + split, + src, + src_dict, + tgt, + tgt_dict, + combine, + dataset_impl, + upsample_primary, + max_source_positions, + prepend_bos=False, + load_alignments=False, + truncate_source=False, + ): + + src_datasets = [] + tgt_datasets = [] + + for k in itertools.count(): + split_k = split + (str(k) if k > 0 else "") + + # infer langcode + if self.split_exists(split_k, src, tgt, src, data_path, dataset_impl): + prefix = os.path.join(data_path, "{}.{}-{}.".format(split_k, src, tgt)) + elif self.split_exists(split_k, tgt, src, src, data_path, dataset_impl): + prefix = os.path.join(data_path, "{}.{}-{}.".format(split_k, tgt, src)) + else: + if k > 0: + break + else: + logger.error( + f"Dataset not found: {data_path}, {split_k}, {src}, {tgt}" + ) + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, data_path) + ) + + src_dataset = self.load_data(prefix + src, src_dict, dataset_impl) + if truncate_source: + src_dataset = AppendTokenDataset( + TruncateDataset( + StripTokenDataset(src_dataset, src_dict.eos()), + max_source_positions - 1, + ), + src_dict.eos(), + ) + src_datasets.append(src_dataset) + tgt_datasets.append(self.load_data(prefix + tgt, tgt_dict, dataset_impl)) + + logger.info( + "{} {} {}-{} {} examples".format( + data_path, split_k, src, tgt, len(src_datasets[-1]) + ) + ) + + if not combine: + break + + assert len(src_datasets) == len(tgt_datasets) + + if len(src_datasets) == 1: + src_dataset, tgt_dataset = src_datasets[0], tgt_datasets[0] + else: + sample_ratios = [1] * len(src_datasets) + sample_ratios[0] = upsample_primary + src_dataset = ConcatDataset(src_datasets, sample_ratios) + tgt_dataset = ConcatDataset(tgt_datasets, sample_ratios) + + if prepend_bos: + assert hasattr(src_dict, "bos_index") and hasattr(tgt_dict, "bos_index") + src_dataset = PrependTokenDataset(src_dataset, src_dict.bos()) + tgt_dataset = PrependTokenDataset(tgt_dataset, tgt_dict.bos()) + + align_dataset = None + if load_alignments: + align_path = os.path.join( + data_path, "{}.align.{}-{}".format(split, src, tgt) + ) + if indexed_dataset.dataset_exists(align_path, impl=dataset_impl): + align_dataset = data_utils.load_indexed_dataset( + align_path, None, dataset_impl + ) + + return src_dataset, tgt_dataset, align_dataset + + def load_langpair_dataset( + self, + data_path, + split, + src, + src_dict, + tgt, + tgt_dict, + combine, + dataset_impl, + upsample_primary, + left_pad_source, + left_pad_target, + max_source_positions, + max_target_positions, + prepend_bos=False, + load_alignments=False, + truncate_source=False, + src_dataset_transform_func=lambda dataset: dataset, + tgt_dataset_transform_func=lambda dataset: dataset, + src_lang_id=None, + tgt_lang_id=None, + langpairs_sharing_datasets=None, + ): + norm_direction = "-".join(sorted([src, tgt])) + if langpairs_sharing_datasets is not None: + src_dataset = langpairs_sharing_datasets.get( + (data_path, split, norm_direction, src), "NotInCache" + ) + tgt_dataset = langpairs_sharing_datasets.get( + (data_path, split, norm_direction, tgt), "NotInCache" + ) + align_dataset = langpairs_sharing_datasets.get( + (data_path, split, norm_direction, src, tgt), "NotInCache" + ) + + # a hack: any one is not in cache, we need to reload them + if ( + langpairs_sharing_datasets is None + or src_dataset == "NotInCache" + or tgt_dataset == "NotInCache" + or align_dataset == "NotInCache" + or split != getattr(self.args, "train_subset", None) + ): + # source and target datasets can be reused in reversed directions to save memory + # reversed directions of valid and test data will not share source and target datasets + src_dataset, tgt_dataset, align_dataset = self.load_lang_dataset( + data_path, + split, + src, + src_dict, + tgt, + tgt_dict, + combine, + dataset_impl, + upsample_primary, + max_source_positions=max_source_positions, + prepend_bos=prepend_bos, + load_alignments=load_alignments, + truncate_source=truncate_source, + ) + src_dataset = src_dataset_transform_func(src_dataset) + tgt_dataset = tgt_dataset_transform_func(tgt_dataset) + if langpairs_sharing_datasets is not None: + langpairs_sharing_datasets[ + (data_path, split, norm_direction, src) + ] = src_dataset + langpairs_sharing_datasets[ + (data_path, split, norm_direction, tgt) + ] = tgt_dataset + langpairs_sharing_datasets[ + (data_path, split, norm_direction, src, tgt) + ] = align_dataset + if align_dataset is None: + # no align data so flag the reverse direction as well in sharing + langpairs_sharing_datasets[ + (data_path, split, norm_direction, tgt, src) + ] = align_dataset + else: + logger.info( + f"Reusing source and target datasets of [{split}] {tgt}-{src} for reversed direction: " + f"[{split}] {src}-{tgt}: src length={len(src_dataset)}; tgt length={len(tgt_dataset)}" + ) + + return LanguagePairDataset( + src_dataset, + src_dataset.sizes, + src_dict, + tgt_dataset, + tgt_dataset.sizes if tgt_dataset is not None else None, + tgt_dict, + left_pad_source=left_pad_source, + left_pad_target=left_pad_target, + align_dataset=align_dataset, + src_lang_id=src_lang_id, + tgt_lang_id=tgt_lang_id, + ) + + def src_dataset_tranform_func(self, src_lang, tgt_lang, dataset, spec=None): + if self.args.lang_tok_replacing_bos_eos: + # it is handled by self.alter_dataset_langtok + # TODO: Unifiy with alter_dataset_langtok + return dataset + if spec is None: + return dataset + tok = self.get_encoder_langtok(src_lang, tgt_lang, spec) + if tok: + return PrependTokenDataset(dataset, tok) + return dataset + + def tgt_dataset_tranform_func(self, source_lang, target_lang, dataset, spec=None): + if dataset is None: + # note that target dataset can be None during inference time + return None + if self.args.lang_tok_replacing_bos_eos: + # TODO: Unifiy with alter_dataset_langtok + # It is handled by self.alter_dataset_langtok. + # The complication in self.alter_dataset_langtok + # makes a unified framework difficult. + return dataset + # if not self.args.decoder_langtok: + if not spec: + return dataset + tok = self.get_decoder_langtok(target_lang, spec) + if tok: + return PrependTokenDataset(dataset, tok) + return dataset + + def alter_dataset_langtok( + self, + lang_pair_dataset, + src_eos=None, + src_lang=None, + tgt_eos=None, + tgt_lang=None, + src_langtok_spec=None, + tgt_langtok_spec=None, + ): + if src_langtok_spec is None and tgt_langtok_spec is None: + return lang_pair_dataset + + new_src_eos = None + if ( + src_langtok_spec is not None + and src_eos is not None + and (src_lang is not None or tgt_lang is not None) + ): + new_src_eos = self.get_encoder_langtok(src_lang, tgt_lang, src_langtok_spec) + else: + src_eos = None + + new_tgt_bos = None + if tgt_langtok_spec and tgt_eos is not None and tgt_lang is not None: + new_tgt_bos = self.get_decoder_langtok(tgt_lang, tgt_langtok_spec) + else: + tgt_eos = None + + return TransformEosLangPairDataset( + lang_pair_dataset, + src_eos=src_eos, + new_src_eos=new_src_eos, + tgt_bos=tgt_eos, + new_tgt_bos=new_tgt_bos, + ) + + def load_a_dataset( + self, + split, + data_path, + src, + src_dict, + tgt, + tgt_dict, + combine, + prepend_bos=False, + langpairs_sharing_datasets=None, + data_category=None, + **extra_kwargs, + ): + dataset_impl = self.args.dataset_impl + upsample_primary = self.args.upsample_primary + left_pad_source = self.args.left_pad_source + left_pad_target = self.args.left_pad_target + max_source_positions = self.args.max_source_positions + max_target_positions = self.args.max_target_positions + load_alignments = self.args.load_alignments + truncate_source = self.args.truncate_source + src_dataset_transform_func = self.src_dataset_tranform_func + tgt_dataset_transform_func = self.tgt_dataset_tranform_func + enable_lang_ids = self.args.enable_lang_ids + lang_dictionary = self.lang_dict + src_langtok_spec, tgt_langtok_spec = extra_kwargs["langtok_spec"] + + src_langtok = self.get_encoder_langtok(src, tgt, src_langtok_spec) + tgt_langtok = self.get_decoder_langtok(tgt, tgt_langtok_spec) + logger.info( + f"{data_category}:{src}-{tgt} src_langtok: {src_langtok}; tgt_langtok: {tgt_langtok}" + ) + + langpair_ds = self.load_langpair_dataset( + data_path, + split, + src, + src_dict, + tgt, + tgt_dict, + combine, + dataset_impl, + upsample_primary, + left_pad_source, + left_pad_target, + max_source_positions, + max_target_positions, + prepend_bos, + load_alignments, + truncate_source, + src_dataset_transform_func=lambda dataset: src_dataset_transform_func( + src, tgt, dataset, src_langtok_spec + ), + tgt_dataset_transform_func=lambda dataset: tgt_dataset_transform_func( + src, tgt, dataset, tgt_langtok_spec + ), + src_lang_id=_lang_id(lang_dictionary, src) + if enable_lang_ids and lang_dictionary is not None + else None, + tgt_lang_id=_lang_id(lang_dictionary, tgt) + if enable_lang_ids and lang_dictionary is not None + else None, + langpairs_sharing_datasets=langpairs_sharing_datasets, + ) + # TODO: handle modified lang toks for mined data and dae data + if self.args.lang_tok_replacing_bos_eos: + ds = self.alter_dataset_langtok( + langpair_ds, + src_eos=self.get_source_dictionary(src).eos() + if src + else self.get_target_dictionary(tgt).eos(), + src_lang=src, + tgt_eos=self.get_target_dictionary(tgt).eos(), + tgt_lang=tgt, + src_langtok_spec=src_langtok_spec, + tgt_langtok_spec=tgt_langtok_spec, + ) + else: + ds = langpair_ds + return ds + + def load_split_langpair_datasets(self, split, data_param_list): + datasets = [] + langpairs_sharing_datasets = ( + {} if self.args.enable_reservsed_directions_shared_datasets else None + ) + for param in data_param_list: + ds = self.load_a_dataset( + split=split, + langpairs_sharing_datasets=langpairs_sharing_datasets, + **param, + ) + datasets.append(ds) + return datasets + + def get_data_paths_and_lang_pairs(self, split): + datapaths = {"main": self.args.data} + lang_pairs = {"main": self.lang_pairs} + if split == getattr(self.args, "train_subset", None): + # only training data can have extra data and extra language pairs + if self.args.extra_data: + extra_datapaths = self.args.extra_data + datapaths.update(extra_datapaths) + if self.args.extra_lang_pairs: + extra_lang_pairs = { + k: v.split(",") for k, v in self.args.extra_lang_pairs.items() + } + lang_pairs.update(extra_lang_pairs) + return datapaths, lang_pairs + + @classmethod + def get_dataset_key(cls, data_category, src, tgt): + return f"{data_category}:{src}-{tgt}" + + @classmethod + def _get_shard_num_dict(cls, split, paths): + shards = defaultdict(int) + for path in paths: + files = PathManager.ls(path) + directions = set() + for f in files: + if f.startswith(split) and f.endswith(".idx"): + # idx files of the form "{split}.{src}-{tgt}.{lang}.idx" + direction = f.split(".")[-3] + directions.add(direction) + for direction in directions: + shards[direction] += 1 + return shards + + def get_split_num_data_shards(self, split): + if split in self._num_shards_dict: + return self._num_shards_dict[split] + num_shards_dict = {} + data_paths, lang_pairs = self.get_data_paths_and_lang_pairs(split) + + for data_category, paths in data_paths.items(): + if data_category not in lang_pairs: + continue + paths = utils.split_paths(paths) + shards_dict = self._get_shard_num_dict(split, paths) + lang_dirs = [ + lang_pair.split("-") for lang_pair in lang_pairs[data_category] + ] + lang_dirs = [x if len(x) > 1 else (x[0], x[0]) for x in lang_dirs] + for src, tgt in lang_dirs: + key = self.get_dataset_key(data_category, src, tgt) + if "mono_" in data_category: + # monolingual data requires tgt only + assert src is None or src == tgt, ( + f"error: src={src}, " + f"tgt={tgt} for data_category={data_category}" + ) + num_shards_dict[key] = shards_dict[tgt] + else: + if f"{src}-{tgt}" in shards_dict: + num_shards_dict[key] = shards_dict[f"{src}-{tgt}"] + elif f"{tgt}-{src}" in shards_dict: + # follow the fairseq tradition to use reversed direction data if it is not available + num_shards_dict[key] = shards_dict[f"{tgt}-{src}"] + self._num_shards_dict[split] = num_shards_dict + logger.info(f"[{split}] num of shards: {num_shards_dict}") + return num_shards_dict + + @classmethod + def get_shard_id(cls, num_shards, epoch, shard_epoch=None): + shard = epoch if shard_epoch is None else shard_epoch + shard = (shard - 1) % num_shards + return shard + + def get_split_data_path(self, paths, epoch, shard_epoch, num_shards): + path = paths[self.get_shard_id(num_shards, epoch, shard_epoch)] + return path + + def get_split_data_param_list(self, split, epoch, shard_epoch=None): + # TODO: to extend with extra datasets and keys and loop over different shard data paths + param_list = [] + data_paths, lang_pairs = self.get_data_paths_and_lang_pairs(split) + logger.info(f"langtoks settings: {self.args.langtoks}") + split_num_shards_dict = self.get_split_num_data_shards(split) + for data_category, paths in data_paths.items(): + if data_category not in lang_pairs: + continue + paths = utils.split_paths(paths) + assert len(paths) > 0 + if len(paths) > 1: + self._has_sharded_data = True + if split != getattr(self.args, "train_subset", None): + # if not training data set, use the first shard for valid and test + paths = paths[:1] + + if data_category in self.args.langtoks: + lang_tok_spec = self.args.langtoks[data_category] + else: + # default to None + lang_tok_spec = (None, None) + + # infer langcode + lang_dirs = [ + lang_pair.split("-") for lang_pair in lang_pairs[data_category] + ] + lang_dirs = [x if len(x) > 1 else (x[0], x[0]) for x in lang_dirs] + for src, tgt in lang_dirs: + assert src is not None or data_category == "mono_dae", ( + f"error: src={src}, " f"tgt={tgt} for data_category={data_category}" + ) + # logger.info(f"preparing param for {data_category}: {src} - {tgt}") + key = self.get_dataset_key(data_category, src, tgt) + data_path = self.get_split_data_path( + paths, epoch, shard_epoch, split_num_shards_dict[key] + ) + param_list.append( + { + "key": key, + "data_path": data_path, + "split": split, + "src": src, + "src_dict": self.get_source_dictionary(src) + if src and data_category != "mono_dae" + else None, + "tgt": tgt, + "tgt_dict": self.get_target_dictionary(tgt), + "data_category": data_category, + "langtok_spec": lang_tok_spec, + } + ) + return param_list + + def get_train_dataset_sizes( + self, data_param_list, datasets, epoch, shard_epoch=None + ): + num_shards = [ + self.get_split_num_data_shards(param["split"])[param["key"]] + for param in data_param_list + ] + data_sizes = [] + for (key, d), num_shard in zip(datasets, num_shards): + my_data_sizes = self._training_data_sizes[key] + shard_ind = self.get_shard_id(num_shard, epoch, shard_epoch) + if shard_ind not in my_data_sizes: + my_data_sizes[shard_ind] = len(d) + known_size = max(my_data_sizes.values()) + data_sizes.append( + # If we don't know the data size of the shard yet, + # use the the max known data size to approximate. + # Note that we preprocess shards by a designated shard size + # and put any remaining data at the end into the last shard so + # the max shard size approximation is almost correct before loading + # the last shard; after loading the last shard, it will have the + # exact data sizes of the whole data size. + (key, sum(my_data_sizes.get(i, known_size) for i in range(num_shard))) + ) + logger.info( + f"estimated total data sizes of all shards used in sampling ratios: {data_sizes}. " + "Note that if the data a shard has not been loaded yet, use the max known data size to approximate" + ) + return [s for _, s in data_sizes] + + def get_train_sampling_ratios( + self, data_param_list, datasets, epoch=1, shard_epoch=None + ): + data_sizes = self.get_train_dataset_sizes( + data_param_list, datasets, epoch, shard_epoch + ) + sampling_func = self.sampling_method.sampling_method_selector() + sample_ratios = sampling_func(data_sizes) if sampling_func is not None else None + return sample_ratios + + def get_sampling_ratios(self, data_param_list, datasets, epoch, shard_epoch=None): + if self.args.sampling_weights_from_file: + weights = load_sampling_weights(self.args.sampling_weights_from_file) + sample_ratios = [weights[k] for k, _ in datasets] + logger.info( + "| ignoring --sampling-weights when loadding sampling weights " + f"from file {self.args.sampling_weights_from_file}" + ) + elif self.args.sampling_weights: + sample_ratios = [self.args.sampling_weights[k] for k, _ in datasets] + else: + sample_ratios = self.get_train_sampling_ratios( + data_param_list, datasets, epoch, shard_epoch + ) + + if sample_ratios is not None: + logger.info( + "| Upsample ratios: {}".format( + list(zip(map(lambda x: x["key"], data_param_list), sample_ratios)) + ) + ) + assert len(sample_ratios) == len(datasets) + return sample_ratios + + def load_split_datasets( + self, split, training, epoch=1, combine=False, shard_epoch=None, **kwargs + ): + data_param_list = self.get_split_data_param_list( + split, epoch, shard_epoch=shard_epoch + ) + langpairs_sharing_datasets = ( + {} if self.args.enable_reservsed_directions_shared_datasets else None + ) + datasets = [ + ( + param["key"], + self.load_a_dataset( + combine=combine, + langpairs_sharing_datasets=langpairs_sharing_datasets, + **param, + ), + ) + for param in data_param_list + ] + return datasets, data_param_list + + def load_into_concat_dataset(self, split, datasets, data_param_list): + if self.args.lang_tok_replacing_bos_eos: + # TODO: to investigate why TransformEosLangPairDataset doesn't work with ConcatDataset + return SampledMultiDataset( + OrderedDict(datasets), + sampling_ratios=None, + eval_key=None, + collate_format=CollateFormat.single, + virtual_size=None, + split=split, + ) + return ConcatDataset([d for _, d in datasets]) + + def load_sampled_multi_epoch_dataset( + self, split, training, epoch=0, combine=False, shard_epoch=None, **kwargs + ): + datasets, data_param_list = self.load_split_datasets( + split, training, epoch, combine, shard_epoch=shard_epoch, **kwargs + ) + if training and split == getattr(self.args, "train_subset", None): + sample_ratios = self.get_sampling_ratios(data_param_list, datasets, epoch) + return SampledMultiEpochDataset( + OrderedDict(datasets), + epoch=epoch, + shard_epoch=shard_epoch, + # valid and test datasets will be degenerate to concating datasets: + sampling_ratios=sample_ratios, + eval_key=None, + collate_format=CollateFormat.single, + virtual_size=self.args.virtual_data_size, + split=split, + virtual_epoch_size=self.args.virtual_epoch_size, + # if not using lang_tok altering, simplified to use the same collater + shared_collater=self._shared_collater(), + ) + else: + return self.load_into_concat_dataset(split, datasets, data_param_list) + + def load_sampled_multi_dataset( + self, split, training, epoch=0, combine=False, shard_epoch=None, **kwargs + ): + datasets, data_param_list = self.load_split_datasets( + split, training, epoch, combine, shard_epoch=shard_epoch, **kwargs + ) + if training and split == getattr(self.args, "train_subset", None): + sample_ratios = self.get_sampling_ratios(data_param_list, datasets, epoch) + return SampledMultiDataset( + OrderedDict(datasets), + epoch=epoch, + # valid and test datasets will be degerate to concating datasets: + sampling_ratios=sample_ratios, + eval_key=None, + collate_format=CollateFormat.single, + virtual_size=self.args.virtual_data_size, + split=split, + # if not using lang_tok altering, simplified to use the same collater + shared_collater=self._shared_collater(), + ) + else: + return self.load_into_concat_dataset(split, datasets, data_param_list) + + def load_dataset( + self, split, training, epoch=0, combine=False, shard_epoch=None, **kwargs + ): + if self.args.virtual_epoch_size is None: + return self.load_sampled_multi_dataset( + split, training, epoch, combine, shard_epoch, **kwargs + ) + else: + return self.load_sampled_multi_epoch_dataset( + split, training, epoch, combine, shard_epoch, **kwargs + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/multilingual_utils.py b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/multilingual_utils.py new file mode 100644 index 00000000..b4e0f982 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/multilingual_utils.py @@ -0,0 +1,63 @@ +from enum import Enum +from typing import Dict, List, Optional, Sequence + +import torch +from fairseq.data import Dictionary + + +class EncoderLangtok(Enum): + """ + Prepend to the beginning of source sentence either the + source or target language token. (src/tgt). + """ + + src = "src" + tgt = "tgt" + + +class LangTokSpec(Enum): + main = "main" + mono_dae = "mono_dae" + + +class LangTokStyle(Enum): + multilingual = "multilingual" + mbart = "mbart" + + +@torch.jit.export +def get_lang_tok( + lang: str, lang_tok_style: str, spec: str = LangTokSpec.main.value +) -> str: + # TOKEN_STYLES can't be defined outside this fn since it needs to be + # TorchScriptable. + TOKEN_STYLES: Dict[str, str] = { + LangTokStyle.mbart.value: "[{}]", + LangTokStyle.multilingual.value: "__{}__", + } + + if spec.endswith("dae"): + lang = f"{lang}_dae" + elif spec.endswith("mined"): + lang = f"{lang}_mined" + style = TOKEN_STYLES[lang_tok_style] + return style.format(lang) + + +def augment_dictionary( + dictionary: Dictionary, + language_list: List[str], + lang_tok_style: str, + langtoks_specs: Sequence[str] = (LangTokSpec.main.value,), + extra_data: Optional[Dict[str, str]] = None, +) -> None: + for spec in langtoks_specs: + for language in language_list: + dictionary.add_symbol( + get_lang_tok(lang=language, lang_tok_style=lang_tok_style, spec=spec) + ) + + if lang_tok_style == LangTokStyle.mbart.value or ( + extra_data is not None and LangTokSpec.mono_dae.value in extra_data + ): + dictionary.add_symbol("") diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampled_multi_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampled_multi_dataset.py new file mode 100644 index 00000000..ece9a972 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampled_multi_dataset.py @@ -0,0 +1,468 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import datetime +import hashlib +import logging +import time +from bisect import bisect_right +from collections import OrderedDict, defaultdict +from enum import Enum +from typing import List + +import numpy as np +import torch + +from fairseq.data import FairseqDataset, data_utils +from fairseq.distributed import utils as distributed_utils + + +def get_time_gap(s, e): + return ( + datetime.datetime.fromtimestamp(e) - datetime.datetime.fromtimestamp(s) + ).__str__() + + +logger = logging.getLogger(__name__) + + +def default_virtual_size_func(datasets, ratios, max_scale_up=1.5): + sizes = [len(d) for d in datasets] + if ratios is None: + return sum(sizes) + largest_idx = np.argmax(sizes) + largest_r = ratios[largest_idx] + largest_s = sizes[largest_idx] + # set virtual sizes relative to the largest dataset + virtual_sizes = [(r / largest_r) * largest_s for r in ratios] + vsize = sum(virtual_sizes) + max_size = sum(sizes) * max_scale_up + return int(vsize if vsize < max_size else max_size) + + +class CollateFormat(Enum): + single = 1 + ordered_dict = 2 + + +class SampledMultiDataset(FairseqDataset): + """Samples from multiple sub-datasets according to given sampling ratios. + Args: + datasets ( + List[~torch.utils.data.Dataset] + or OrderedDict[str, ~torch.utils.data.Dataset] + ): datasets + sampling_ratios (List[float]): list of probability of each dataset to be sampled + (default: None, which corresponds to concatenating all dataset together). + seed (int): RNG seed to use (default: 2). + epoch (int): starting epoch number (default: 1). + eval_key (str, optional): a key used at evaluation time that causes + this instance to pass-through batches from *datasets[eval_key]*. + collate_format (CollateFormat): collater output format, either CollateFormat.ordered_dict or + CollateFormat.single (default: CollateFormat.single) where CollateFormat.single configures + the collater to output batches of data mixed from all sub-datasets, + and CollateFormat.ordered_dict configures the collater to output a dictionary of batches indexed by keys + of sub-datasets. + Note that not all sub-datasets will present in a single batch in both formats. + virtual_size (int, or callable): the expected virtual size of the dataset (default: default_virtual_size_func). + split (str): the split of the data, e.g. 'train', 'valid' or 'test'. + shared_collater (bool): whether or not to all sub-datasets have the same collater. + shuffle (bool): whether or not to shuffle data (default: True). + """ + + def __init__( + self, + datasets, + sampling_ratios=None, + seed=2, + epoch=1, + eval_key=None, + collate_format=CollateFormat.single, + virtual_size=default_virtual_size_func, + split="", + shared_collater=False, + shuffle=True, + ): + super().__init__() + self.shared_collater = shared_collater + self.shuffle = shuffle + + if isinstance(datasets, OrderedDict): + self.keys = list(datasets.keys()) + datasets = list(datasets.values()) + elif isinstance(datasets, List): + self.keys = list(range(len(datasets))) + else: + raise AssertionError() + self.datasets = datasets + self.split = split + + self.eval_key = eval_key + if self.eval_key is not None: + self.collate_format = CollateFormat.single + else: + self.collate_format = collate_format + + self.seed = seed + self._cur_epoch = None + + self.cumulated_sizes = None + # self.datasets[k][self._cur_indices[i]] is the data item i in this sampled dataset + # namely, data item i is sampled from the kth sub-dataset self.datasets[k] + # where self.cumulated_sizes[k-1] <= i < self.cumulated_sizes[k] + self._cur_indices = None + + self._sizes = None + self.virtual_size_per_dataset = None + # caching properties + self._reset_cached_properties() + self.setup_sampling(sampling_ratios, virtual_size) + self.set_epoch(epoch) + + def _clean_if_not_none(self, var_list): + for v in var_list: + if v is not None: + del v + + def _reset_cached_properties(self): + self._clean_if_not_none([self._sizes, self._cur_indices]) + self._sizes = None + self._cur_indices = None + + def setup_sampling(self, sample_ratios, virtual_size): + sizes = [len(d) for d in self.datasets] + if sample_ratios is None: + # default back to concating datasets + self.sample_ratios = None + self.virtual_size = sum(sizes) + else: + if not isinstance(sample_ratios, np.ndarray): + sample_ratios = np.array(sample_ratios) + self.sample_ratios = sample_ratios + virtual_size = ( + default_virtual_size_func if virtual_size is None else virtual_size + ) + self.virtual_size = ( + virtual_size(self.datasets, self.sample_ratios) + if callable(virtual_size) + else virtual_size + ) + + def adjust_sampling(self, epoch, sampling_ratios, virtual_size): + if sampling_ratios is not None: + sampling_ratios = self._sync_sample_ratios(sampling_ratios) + self.setup_sampling(sampling_ratios, virtual_size) + + def _sync_sample_ratios(self, ratios): + # in case the ratios are not precisely the same across processes + # also to ensure every procresses update the ratios in the same pace + ratios = torch.DoubleTensor(ratios) + if torch.distributed.is_initialized(): + if torch.cuda.is_available(): + distributed_utils.all_reduce( + ratios.cuda(), group=distributed_utils.get_data_parallel_group() + ) + else: + distributed_utils.all_reduce( + ratios, group=distributed_utils.get_data_parallel_group() + ) + ret = ratios.cpu() + ret = ret.numpy() + return ret + + def random_choice_in_dataset(self, rng, dataset, choice_size): + if hasattr(dataset, "random_choice_in_dataset"): + return dataset.random_choice_in_dataset(rng, choice_size) + dataset_size = len(dataset) + return rng.choice( + dataset_size, choice_size, replace=(choice_size > dataset_size) + ) + + def get_virtual_indices(self, rng, datasets, sample_ratios, virtual_size): + def get_counts(sample_ratios): + counts = np.array([virtual_size * r for r in sample_ratios], dtype=np.int64) + diff = virtual_size - counts.sum() + assert diff >= 0 + # due to round-offs, the size might not match the desired sizes + if diff > 0: + dataset_indices = rng.choice( + len(sample_ratios), size=diff, p=sample_ratios + ) + for i in dataset_indices: + counts[i] += 1 + return counts + + def get_in_dataset_indices(datasets, sizes, sample_ratios): + counts = get_counts(sample_ratios) + # uniformally sample desired counts for each dataset + # if the desired counts are large, sample with replacement: + indices = [ + self.random_choice_in_dataset(rng, d, c) + for c, d in zip(counts, datasets) + ] + return indices + + sizes = [len(d) for d in datasets] + if sample_ratios is None: + # default back to concating datasets + in_dataset_indices = [list(range(s)) for s in sizes] + virtual_sizes_per_dataset = sizes + else: + ratios = sample_ratios / sample_ratios.sum() + in_dataset_indices = get_in_dataset_indices(datasets, sizes, ratios) + virtual_sizes_per_dataset = [len(d) for d in in_dataset_indices] + virtual_sizes_per_dataset = np.array(virtual_sizes_per_dataset, np.int64) + cumulative_sizes = np.cumsum(virtual_sizes_per_dataset) + assert sum(virtual_sizes_per_dataset) == virtual_size + assert cumulative_sizes[-1] == virtual_size + if virtual_size < sum(sizes): + logger.warning( + f"virtual data size ({virtual_size}) is less than real data size ({sum(sizes)})." + " If virtual size << real data size, there could be data coverage issue." + ) + in_dataset_indices = np.hstack(in_dataset_indices) + return in_dataset_indices, cumulative_sizes, virtual_sizes_per_dataset + + def _get_dataset_and_index(self, index): + i = bisect_right(self.cumulated_sizes, index) + return i, self._cur_indices[index] + + def __getitem__(self, index): + # self.__getitem__(index) returns self.datasets[k][self._cur_indices[index]] + # where k satisfies self.cumulated_sizes[k - 1] <= k < self.cumulated_sizes[k] + ds_idx, ds_sample_idx = self._get_dataset_and_index(index) + ret = (ds_idx, self.datasets[ds_idx][ds_sample_idx]) + return ret + + def num_tokens(self, index): + return self.sizes[index].max() + + def num_tokens_vec(self, indices): + sizes_vec = self.sizes[np.array(indices)] + # max across all dimensions but first one + return np.amax(sizes_vec, axis=tuple(range(1, len(sizes_vec.shape)))) + + def size(self, index): + return self.sizes[index] + + def __len__(self): + return self.virtual_size + + def collater(self, samples, **extra_args): + """Merge a list of samples to form a mini-batch.""" + if len(samples) == 0: + return None + if self.collate_format == "ordered_dict": + collect_samples = [[] for _ in range(len(self.datasets))] + for (i, sample) in samples: + collect_samples[i].append(sample) + batch = OrderedDict( + [ + (self.keys[i], dataset.collater(collect_samples[i])) + for i, (key, dataset) in enumerate(zip(self.keys, self.datasets)) + if len(collect_samples[i]) > 0 + ] + ) + elif self.shared_collater: + batch = self.datasets[0].collater([s for _, s in samples]) + else: + samples_dict = defaultdict(list) + pad_to_length = ( + defaultdict(int) + if "pad_to_length" not in extra_args + else extra_args["pad_to_length"] + ) + for ds_idx, s in samples: + pad_to_length["source"] = max( + pad_to_length["source"], s["source"].size(0) + ) + if s["target"] is not None: + pad_to_length["target"] = max( + pad_to_length["target"], s["target"].size(0) + ) + samples_dict[ds_idx].append(s) + batches = [ + self.datasets[i].collater(samples_dict[i], pad_to_length=pad_to_length) + for i in range(len(self.datasets)) + if len(samples_dict[i]) > 0 + ] + + def straight_data(tensors): + batch = torch.cat(tensors, dim=0) + return batch + + src_lengths = straight_data( + [b["net_input"]["src_lengths"] for b in batches] + ) + src_lengths, sort_order = src_lengths.sort(descending=True) + + def straight_order(tensors): + batch = straight_data(tensors) + return batch.index_select(0, sort_order) + + batch = { + "id": straight_order([b["id"] for b in batches]), + "nsentences": sum(b["nsentences"] for b in batches), + "ntokens": sum(b["ntokens"] for b in batches), + "net_input": { + "src_tokens": straight_order( + [b["net_input"]["src_tokens"] for b in batches] + ), + "src_lengths": src_lengths, + }, + "target": straight_order([b["target"] for b in batches]) + if batches[0]["target"] is not None + else None, + } + if "prev_output_tokens" in batches[0]["net_input"]: + batch["net_input"]["prev_output_tokens"] = straight_order( + [b["net_input"]["prev_output_tokens"] for b in batches] + ) + if "src_lang_id" in batches[0]["net_input"]: + batch["net_input"]["src_lang_id"] = straight_order( + [b["net_input"]["src_lang_id"] for b in batches] + ) + if "tgt_lang_id" in batches[0]: + batch["tgt_lang_id"] = straight_order( + [b["tgt_lang_id"] for b in batches] + ) + return batch + + @property + def sizes(self): + if self._sizes is not None: + return self._sizes + start_time = time.time() + in_sub_dataset_indices = [ + self._cur_indices[ + 0 if i == 0 else self.cumulated_sizes[i - 1] : self.cumulated_sizes[i] + ] + for i in range(len(self.datasets)) + ] + sub_dataset_sizes = [ + d.sizes[indices] + for d, indices in zip(self.datasets, in_sub_dataset_indices) + ] + self._sizes = np.vstack(sub_dataset_sizes) + logger.info(f"sizes() calling time: {get_time_gap(start_time, time.time())}") + return self._sizes + + def ordered_indices(self): + if self.shuffle: + indices = np.random.permutation(len(self)) + else: + indices = np.arange(len(self)) + + sizes = self.sizes + tgt_sizes = sizes[:, 1] if len(sizes.shape) > 0 and sizes.shape[1] > 1 else None + src_sizes = ( + sizes[:, 0] if len(sizes.shape) > 0 and sizes.shape[1] > 1 else sizes + ) + + # sort by target length, then source length + if tgt_sizes is not None: + indices = indices[np.argsort(tgt_sizes[indices], kind="mergesort")] + sort_indices = indices[np.argsort(src_sizes[indices], kind="mergesort")] + return sort_indices + + def prefetch(self, indices): + prefetch_indices = [[] for _ in range(len(self.datasets))] + for i in indices: + ds_idx, ds_sample_idx = self._get_dataset_and_index(i) + prefetch_indices[ds_idx].append(ds_sample_idx) + for i in range(len(prefetch_indices)): + self.datasets[i].prefetch(prefetch_indices[i]) + + @property + def can_reuse_epoch_itr_across_epochs(self): + return False + + def set_epoch(self, epoch): + super().set_epoch(epoch) + if epoch == self._cur_epoch: + # re-enter so return + return + for d in self.datasets: + if hasattr(d, "set_epoch"): + d.set_epoch(epoch) + self._cur_epoch = epoch + self._establish_virtual_datasets() + + def _establish_virtual_datasets(self): + if self.sample_ratios is None and self._cur_indices is not None: + # not a samping dataset, no need to resample if indices are already established + return + self._reset_cached_properties() + + start_time = time.time() + # Generate a weighted sample of indices as a function of the + # random seed and the current epoch. + rng = np.random.RandomState( + [ + int( + hashlib.sha1( + str(self.__class__.__name__).encode("utf-8") + ).hexdigest(), + 16, + ) + % (2**32), + self.seed % (2**32), # global seed + self._cur_epoch, # epoch index, + ] + ) + self._clean_if_not_none( + [self.cumulated_sizes, self.virtual_size_per_dataset, self._sizes] + ) + self._sizes = None + + indices, cumulated_sizes, virtual_size_per_dataset = self.get_virtual_indices( + rng, self.datasets, self.sample_ratios, self.virtual_size + ) + self._cur_indices = indices + self.cumulated_sizes = cumulated_sizes + self.virtual_size_per_dataset = virtual_size_per_dataset + + raw_sizes = [len(d) for d in self.datasets] + sampled_sizes = self.virtual_size_per_dataset + logger.info( + f"[{self.split}] Raw sizes: {str(dict(zip(self.keys, raw_sizes)))}; " + f"raw total size: {sum(raw_sizes)}" + ) + logger.info( + f"[{self.split}] Resampled sizes: {str(dict(zip(self.keys, sampled_sizes)))}; " + f"resampled total size: {sum(sampled_sizes)}" + ) + if self.sample_ratios is not None: + logger.info( + f"[{self.split}] Upsampling ratios: {str(dict(zip(self.keys, self.sample_ratios)))}" + ) + else: + logger.info(f"[{self.split}] A concat dataset") + logger.info( + f"[{self.split}] virtual dataset established time: {get_time_gap(start_time, time.time())}" + ) + + def filter_indices_by_size(self, indices, max_sizes): + """Filter a list of sample indices. Remove those that are longer + than specified in max_sizes. + + Args: + indices (np.array): original array of sample indices + max_sizes (int or list[int] or tuple[int]): max sample size, + can be defined separately for src and tgt (then list or tuple) + + Returns: + np.array: filtered sample array + list: list of removed indices + """ + sizes = self.sizes + tgt_sizes = sizes[:, 1] if len(sizes.shape) > 0 and sizes.shape[1] > 1 else None + src_sizes = ( + sizes[:, 0] if len(sizes.shape) > 0 and sizes.shape[1] > 1 else sizes + ) + + return data_utils.filter_paired_dataset_indices_by_size( + src_sizes, tgt_sizes, indices, max_sizes + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampled_multi_epoch_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampled_multi_epoch_dataset.py new file mode 100644 index 00000000..bb187a8d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampled_multi_epoch_dataset.py @@ -0,0 +1,199 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import hashlib +import logging +import math + +import numpy as np + +from fairseq.data import SampledMultiDataset + +from .sampled_multi_dataset import CollateFormat, default_virtual_size_func + +logger = logging.getLogger(__name__) + + +class SampledMultiEpochDataset(SampledMultiDataset): + """Samples from multiple sub-datasets according to sampling ratios + using virtual epoch sizes to speed up dataloading. + Args: + datasets ( + List[~torch.utils.data.Dataset] + or OrderedDict[str, ~torch.utils.data.Dataset] + ): datasets + sampling_ratios (List[float]): list of probability of each dataset to be sampled + (default: None, which corresponds to concating all dataset together). + seed (int): RNG seed to use (default: 2). + epoch (int): starting epoch number (default: 1). + eval_key (str, optional): a key used at evaluation time that causes + this instance to pass-through batches from *datasets[eval_key]*. + collate_format (CollateFormat): collater output format, either CollateFormat.ordered_dict or + CollateFormat.single (default: CollateFormat.single) where CollateFormat.single configures + the collater to output batches of data mixed from all sub-datasets, + and CollateFormat.ordered_dict configures the collater to output a dictionary of batches indexed by keys + of sub-datasets. + Note that not all sub-datasets will present in a single batch in both formats. + virtual_size (int, or callable): the expected virtual size of the dataset (default: default_virtual_size_func). + split (str): the split of the data, e.g. 'train', 'valid' or 'test'. + virtual_epoch_size (int): virtual epoch size, the dataset will go through the data by + this virtual epoch size one by one to speed up data loading, e.g. indicing and filtering + can be performed whenever a virtual epoch is loaded without waiting for the whole dataset to be loaded. + shared_collater (bool): whether or not to all sub-datasets have the same collater. + shard_epoch (int): the real epoch number for shard selection. + shuffle (bool): whether or not to shuffle data (default: True). + """ + + def __init__( + self, + datasets, + sampling_ratios=None, + seed=2, + epoch=1, + eval_key=None, + collate_format=CollateFormat.single, + virtual_size=default_virtual_size_func, + split="", + virtual_epoch_size=None, + shared_collater=False, + shard_epoch=1, + shuffle=True, + ): + self.virtual_epoch_size = virtual_epoch_size + self._current_epoch_start_index = None + self._random_global_indices = None + self.shard_epoch = shard_epoch if shard_epoch is not None else 1 + self.load_next_shard = None + self._epoch_sizes = None + super().__init__( + datasets=datasets, + sampling_ratios=sampling_ratios, + seed=seed, + epoch=epoch, + eval_key=eval_key, + collate_format=collate_format, + virtual_size=virtual_size, + split=split, + shared_collater=shared_collater, + shuffle=shuffle, + ) + + def _setup(self, epoch): + self.virtual_epoch_size = ( + self.virtual_epoch_size + if self.virtual_epoch_size is not None + else self.virtual_size + ) + if self.virtual_epoch_size > self.virtual_size: + logger.warning( + f"virtual epoch size {self.virtual_epoch_size} " + f"is greater than virtual dataset size {self.virtual_size}" + ) + self.virtual_epoch_size = self.virtual_size + self.num_virtual_epochs = math.ceil(self.virtual_size / self.virtual_epoch_size) + self._current_epoch_start_index = self._get_epoch_start_index(epoch) + logger.info( + f"virtual epoch size {self.virtual_epoch_size}; virtual dataset size {self.virtual_size}" + ) + + def _map_epoch_index_to_global(self, index): + index = self._current_epoch_start_index + index + # add randomness + return self._random_global_indices[index] + + @property + def sizes(self): + if self._epoch_sizes is not None: + return self._epoch_sizes + _sizes = super().sizes + indices = self._random_global_indices[ + self._current_epoch_start_index : self._current_epoch_start_index + + len(self) + ] + self._epoch_sizes = _sizes[indices] + # del super()._sizes to save memory + del self._sizes + self._sizes = None + return self._epoch_sizes + + def _get_dataset_and_index(self, index): + i = self._map_epoch_index_to_global(index) + return super()._get_dataset_and_index(i) + + def __len__(self): + return ( + self.virtual_epoch_size + if self._current_epoch_start_index + self.virtual_epoch_size + < self.virtual_size + else self.virtual_size - self._current_epoch_start_index + ) + + def set_epoch(self, epoch): + if self._current_epoch_start_index is None: + # initializing epoch idnices of a virtual dataset + self._setup(epoch) + self._next_virtual_epoch(epoch) + else: + # working on already intialized epoch indices + if epoch == self._cur_epoch: + # re-enter so return + return + self._next_virtual_epoch(epoch) + + def _get_epoch_start_index(self, epoch): + assert epoch >= 1 # fairseq is using 1-based epoch everywhere + return ((epoch - 1) % self.num_virtual_epochs) * self.virtual_epoch_size + + def _next_global_indices(self, epoch): + rng = np.random.RandomState( + [ + int( + hashlib.sha1( + str(self.__class__.__name__).encode("utf-8") + ).hexdigest(), + 16, + ) + % (2**32), + self.seed % (2**32), # global seed + epoch, # epoch index, + ] + ) + del self._random_global_indices + self._random_global_indices = rng.choice( + self.virtual_size, self.virtual_size, replace=False + ) + if self.load_next_shard is None: + self.load_next_shard = False + else: + # increase shard epoch for next loading + self.shard_epoch += 1 + self.load_next_shard = True + logger.info( + "to load next epoch/shard in next load_dataset: " + f"epoch={epoch}/shard_epoch={self.shard_epoch}" + ) + + def _next_virtual_epoch(self, epoch): + index = self._get_epoch_start_index(epoch) + if index == 0 or self._random_global_indices is None: + # need to start from the beginning, + # so call super().set_epoch(epoch) to establish the global virtual indices + logger.info( + "establishing a new set of global virtual indices for " + f"epoch={epoch}/shard_epoch={self.shard_epoch}" + ) + super().set_epoch(epoch) + self._next_global_indices(epoch) + else: + self._cur_epoch = epoch + + # reset cache sizes and ordered_indices for the epoch after moving to a new epoch + self._clean_if_not_none( + [ + self._epoch_sizes, + ] + ) + self._epoch_sizes = None + self._current_epoch_start_index = index diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampling_method.py b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampling_method.py new file mode 100644 index 00000000..140c68f0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/multilingual/sampling_method.py @@ -0,0 +1,78 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from typing import List + + +logger = logging.getLogger(__name__) + + +def uniform(dataset_sizes: List[int]): + return [1.0] * len(dataset_sizes) + + +def temperature_sampling(dataset_sizes, temp): + total_size = sum(dataset_sizes) + return [(size / total_size) ** (1.0 / temp) for size in dataset_sizes] + + +def make_temperature_sampling(temp=1.0): + def sampling_func(dataset_sizes): + return temperature_sampling(dataset_sizes, temp) + + return sampling_func + + +def make_ratio_sampling(ratios): + def sampling_func(dataset_sizes): + return ratios + + return sampling_func + + +class SamplingMethod: + @staticmethod + def add_arguments(parser): + parser.add_argument( + "--sampling-method", + choices=[ + "uniform", + "temperature", + "concat", + "RoundRobin", + ], + type=str, + default="concat", + help="The method to sample data per language pairs", + ) + parser.add_argument( + "--sampling-temperature", + default=1.5, + type=float, + help="only work with --sampling-method temperature", + ) + + @staticmethod + def build_sampler(args, task): + return SamplingMethod(args, task) + + def __init__(self, args, task): + self.args = args + self.task = task + + def is_adaptive(self): + return False + + def sampling_method_selector(self): + args = self.args + logger.info(f"selected sampler: {args.sampling_method}") + if args.sampling_method == "uniform": + return uniform + elif args.sampling_method == "temperature" or self.is_adaptive(): + return make_temperature_sampling(float(args.sampling_temperature)) + else: + # default to concating all data set together + return None diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/nested_dictionary_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/nested_dictionary_dataset.py new file mode 100644 index 00000000..52e74abd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/nested_dictionary_dataset.py @@ -0,0 +1,125 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections import OrderedDict + +import torch +from torch.utils.data.dataloader import default_collate + +from . import FairseqDataset + + +def _flatten(dico, prefix=None): + """Flatten a nested dictionary.""" + new_dico = OrderedDict() + if isinstance(dico, dict): + prefix = prefix + "." if prefix is not None else "" + for k, v in dico.items(): + if v is None: + continue + new_dico.update(_flatten(v, prefix + k)) + elif isinstance(dico, list): + for i, v in enumerate(dico): + new_dico.update(_flatten(v, prefix + ".[" + str(i) + "]")) + else: + new_dico = OrderedDict({prefix: dico}) + return new_dico + + +def _unflatten(dico): + """Unflatten a flattened dictionary into a nested dictionary.""" + new_dico = OrderedDict() + for full_k, v in dico.items(): + full_k = full_k.split(".") + node = new_dico + for k in full_k[:-1]: + if k.startswith("[") and k.endswith("]"): + k = int(k[1:-1]) + if k not in node: + node[k] = OrderedDict() + node = node[k] + node[full_k[-1]] = v + return new_dico + + +class NestedDictionaryDataset(FairseqDataset): + def __init__(self, defn, sizes=None): + super().__init__() + self.defn = _flatten(defn) + self.sizes = [sizes] if not isinstance(sizes, (list, tuple)) else sizes + + first = None + for v in self.defn.values(): + if not isinstance( + v, + ( + FairseqDataset, + torch.utils.data.Dataset, + ), + ): + raise ValueError("Expected Dataset but found: {}".format(v.__class__)) + first = first or v + if len(v) > 0: + assert len(v) == len(first), "dataset lengths must match" + + self._len = len(first) + + def __getitem__(self, index): + return OrderedDict((k, ds[index]) for k, ds in self.defn.items()) + + def __len__(self): + return self._len + + def collater(self, samples): + """Merge a list of samples to form a mini-batch. + + Args: + samples (List[dict]): samples to collate + + Returns: + dict: a mini-batch suitable for forwarding with a Model + """ + if len(samples) == 0: + return {} + sample = OrderedDict() + for k, ds in self.defn.items(): + try: + sample[k] = ds.collater([s[k] for s in samples]) + except NotImplementedError: + sample[k] = default_collate([s[k] for s in samples]) + return _unflatten(sample) + + def num_tokens(self, index): + """Return the number of tokens in a sample. This value is used to + enforce ``--max-tokens`` during batching.""" + return max(s[index] for s in self.sizes) + + def size(self, index): + """Return an example's size as a float or tuple. This value is used when + filtering a dataset with ``--max-positions``.""" + if len(self.sizes) == 1: + return self.sizes[0][index] + else: + return (s[index] for s in self.sizes) + + @property + def supports_prefetch(self): + """Whether this dataset supports prefetching.""" + return any(ds.supports_prefetch for ds in self.defn.values()) + + def prefetch(self, indices): + """Prefetch the data required for this epoch.""" + for ds in self.defn.values(): + if getattr(ds, "supports_prefetch", False): + ds.prefetch(indices) + + @property + def can_reuse_epoch_itr_across_epochs(self): + return all(ds.can_reuse_epoch_itr_across_epochs for ds in self.defn.values()) + + def set_epoch(self, epoch): + super().set_epoch(epoch) + for ds in self.defn.values(): + ds.set_epoch(epoch) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/noising.py b/PyTorch/NLP/new-Transformer/fairseq/data/noising.py new file mode 100644 index 00000000..e92e83c2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/noising.py @@ -0,0 +1,334 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch +from fairseq.data import data_utils + + +class WordNoising(object): + """Generate a noisy version of a sentence, without changing words themselves.""" + + def __init__(self, dictionary, bpe_cont_marker="@@", bpe_end_marker=None): + self.dictionary = dictionary + self.bpe_end = None + if bpe_cont_marker: + self.bpe_end = np.array( + [ + not self.dictionary[i].endswith(bpe_cont_marker) + for i in range(len(self.dictionary)) + ] + ) + elif bpe_end_marker: + self.bpe_end = np.array( + [ + self.dictionary[i].endswith(bpe_end_marker) + for i in range(len(self.dictionary)) + ] + ) + + self.get_word_idx = ( + self._get_bpe_word_idx if self.bpe_end is not None else self._get_token_idx + ) + + def noising(self, x, lengths, noising_prob=0.0): + raise NotImplementedError() + + def _get_bpe_word_idx(self, x): + """ + Given a list of BPE tokens, for every index in the tokens list, + return the index of the word grouping that it belongs to. + For example, for input x corresponding to ["how", "are", "y@@", "ou"], + return [[0], [1], [2], [2]]. + """ + # x: (T x B) + bpe_end = self.bpe_end[x] + + if x.size(0) == 1 and x.size(1) == 1: + # Special case when we only have one word in x. If x = [[N]], + # bpe_end is a scalar (bool) instead of a 2-dim array of bools, + # which makes the sum operation below fail. + return np.array([[0]]) + + # do a reduce front sum to generate word ids + word_idx = bpe_end[::-1].cumsum(0)[::-1] + word_idx = word_idx.max(0)[None, :] - word_idx + return word_idx + + def _get_token_idx(self, x): + """ + This is to extend noising functions to be able to apply to non-bpe + tokens, e.g. word or characters. + """ + x = torch.t(x) + word_idx = np.array([range(len(x_i)) for x_i in x]) + return np.transpose(word_idx) + + +class WordDropout(WordNoising): + """Randomly drop input words. If not passing blank_idx (default is None), + then dropped words will be removed. Otherwise, it will be replaced by the + blank_idx.""" + + def __init__( + self, + dictionary, + default_dropout_prob=0.1, + bpe_cont_marker="@@", + bpe_end_marker=None, + ): + super().__init__(dictionary, bpe_cont_marker, bpe_end_marker) + self.default_dropout_prob = default_dropout_prob + + def noising(self, x, lengths, dropout_prob=None, blank_idx=None): + if dropout_prob is None: + dropout_prob = self.default_dropout_prob + # x: (T x B), lengths: B + if dropout_prob == 0: + return x, lengths + + assert 0 < dropout_prob < 1 + + # be sure to drop entire words + word_idx = self.get_word_idx(x) + sentences = [] + modified_lengths = [] + for i in range(lengths.size(0)): + # Since dropout probabilities need to apply over non-pad tokens, + # it is not trivial to generate the keep mask without consider + # input lengths; otherwise, this could be done outside the loop + + # We want to drop whole words based on word_idx grouping + num_words = max(word_idx[:, i]) + 1 + + # ith example: [x0, x1, ..., eos, pad, ..., pad] + # We should only generate keep probs for non-EOS tokens. Thus if the + # input sentence ends in EOS, the last word idx is not included in + # the dropout mask generation and we append True to always keep EOS. + # Otherwise, just generate the dropout mask for all word idx + # positions. + has_eos = x[lengths[i] - 1, i] == self.dictionary.eos() + if has_eos: # has eos? + keep = np.random.rand(num_words - 1) >= dropout_prob + keep = np.append(keep, [True]) # keep EOS symbol + else: + keep = np.random.rand(num_words) >= dropout_prob + + words = x[: lengths[i], i].tolist() + + # TODO: speed up the following loop + # drop words from the input according to keep + new_s = [ + w if keep[word_idx[j, i]] else blank_idx for j, w in enumerate(words) + ] + new_s = [w for w in new_s if w is not None] + # we need to have at least one word in the sentence (more than the + # start / end sentence symbols) + if len(new_s) <= 1: + # insert at beginning in case the only token left is EOS + # EOS should be at end of list. + new_s.insert(0, words[np.random.randint(0, len(words))]) + assert len(new_s) >= 1 and ( + not has_eos # Either don't have EOS at end or last token is EOS + or (len(new_s) >= 2 and new_s[-1] == self.dictionary.eos()) + ), "New sentence is invalid." + sentences.append(new_s) + modified_lengths.append(len(new_s)) + # re-construct input + modified_lengths = torch.LongTensor(modified_lengths) + modified_x = torch.LongTensor( + modified_lengths.max(), modified_lengths.size(0) + ).fill_(self.dictionary.pad()) + for i in range(modified_lengths.size(0)): + modified_x[: modified_lengths[i], i].copy_(torch.LongTensor(sentences[i])) + + return modified_x, modified_lengths + + +class WordShuffle(WordNoising): + """Shuffle words by no more than k positions.""" + + def __init__( + self, + dictionary, + default_max_shuffle_distance=3, + bpe_cont_marker="@@", + bpe_end_marker=None, + ): + super().__init__(dictionary, bpe_cont_marker, bpe_end_marker) + self.default_max_shuffle_distance = 3 + + def noising(self, x, lengths, max_shuffle_distance=None): + if max_shuffle_distance is None: + max_shuffle_distance = self.default_max_shuffle_distance + # x: (T x B), lengths: B + if max_shuffle_distance == 0: + return x, lengths + + # max_shuffle_distance < 1 will return the same sequence + assert max_shuffle_distance > 1 + + # define noise word scores + noise = np.random.uniform( + 0, + max_shuffle_distance, + size=(x.size(0), x.size(1)), + ) + noise[0] = -1 # do not move start sentence symbol + # be sure to shuffle entire words + word_idx = self.get_word_idx(x) + x2 = x.clone() + for i in range(lengths.size(0)): + length_no_eos = lengths[i] + if x[lengths[i] - 1, i] == self.dictionary.eos(): + length_no_eos = lengths[i] - 1 + # generate a random permutation + scores = word_idx[:length_no_eos, i] + noise[word_idx[:length_no_eos, i], i] + # ensure no reordering inside a word + scores += 1e-6 * np.arange(length_no_eos.item()) + permutation = scores.argsort() + # shuffle words + x2[:length_no_eos, i].copy_( + x2[:length_no_eos, i][torch.from_numpy(permutation)] + ) + return x2, lengths + + +class UnsupervisedMTNoising(WordNoising): + """ + Implements the default configuration for noising in UnsupervisedMT + (github.com/facebookresearch/UnsupervisedMT) + """ + + def __init__( + self, + dictionary, + max_word_shuffle_distance, + word_dropout_prob, + word_blanking_prob, + bpe_cont_marker="@@", + bpe_end_marker=None, + ): + super().__init__(dictionary) + self.max_word_shuffle_distance = max_word_shuffle_distance + self.word_dropout_prob = word_dropout_prob + self.word_blanking_prob = word_blanking_prob + + self.word_dropout = WordDropout( + dictionary=dictionary, + bpe_cont_marker=bpe_cont_marker, + bpe_end_marker=bpe_end_marker, + ) + self.word_shuffle = WordShuffle( + dictionary=dictionary, + bpe_cont_marker=bpe_cont_marker, + bpe_end_marker=bpe_end_marker, + ) + + def noising(self, x, lengths): + # 1. Word Shuffle + noisy_src_tokens, noisy_src_lengths = self.word_shuffle.noising( + x=x, + lengths=lengths, + max_shuffle_distance=self.max_word_shuffle_distance, + ) + # 2. Word Dropout + noisy_src_tokens, noisy_src_lengths = self.word_dropout.noising( + x=noisy_src_tokens, + lengths=noisy_src_lengths, + dropout_prob=self.word_dropout_prob, + ) + # 3. Word Blanking + noisy_src_tokens, noisy_src_lengths = self.word_dropout.noising( + x=noisy_src_tokens, + lengths=noisy_src_lengths, + dropout_prob=self.word_blanking_prob, + blank_idx=self.dictionary.unk(), + ) + + return noisy_src_tokens + + +class NoisingDataset(torch.utils.data.Dataset): + def __init__( + self, + src_dataset, + src_dict, + seed, + noiser=None, + noising_class=UnsupervisedMTNoising, + **kwargs + ): + """ + Wrap a :class:`~torch.utils.data.Dataset` and apply noise to the + samples based on the supplied noising configuration. + + Args: + src_dataset (~torch.utils.data.Dataset): dataset to wrap. + to build self.src_dataset -- + a LanguagePairDataset with src dataset as the source dataset and + None as the target dataset. Should NOT have padding so that + src_lengths are accurately calculated by language_pair_dataset + collate function. + We use language_pair_dataset here to encapsulate the tgt_dataset + so we can re-use the LanguagePairDataset collater to format the + batches in the structure that SequenceGenerator expects. + src_dict (~fairseq.data.Dictionary): source dictionary + seed (int): seed to use when generating random noise + noiser (WordNoising): a pre-initialized :class:`WordNoising` + instance. If this is None, a new instance will be created using + *noising_class* and *kwargs*. + noising_class (class, optional): class to use to initialize a + default :class:`WordNoising` instance. + kwargs (dict, optional): arguments to initialize the default + :class:`WordNoising` instance given by *noiser*. + """ + self.src_dataset = src_dataset + self.src_dict = src_dict + self.seed = seed + self.noiser = ( + noiser + if noiser is not None + else noising_class( + dictionary=src_dict, + **kwargs, + ) + ) + self.sizes = src_dataset.sizes + + def __getitem__(self, index): + """ + Returns a single noisy sample. Multiple samples are fed to the collater + create a noising dataset batch. + """ + src_tokens = self.src_dataset[index] + src_lengths = torch.LongTensor([len(src_tokens)]) + src_tokens = src_tokens.unsqueeze(0) + + # Transpose src tokens to fit expected shape of x in noising function + # (batch size, sequence length) -> (sequence length, batch size) + src_tokens_t = torch.t(src_tokens) + + with data_utils.numpy_seed(self.seed + index): + noisy_src_tokens = self.noiser.noising(src_tokens_t, src_lengths) + + # Transpose back to expected src_tokens format + # (sequence length, 1) -> (1, sequence length) + noisy_src_tokens = torch.t(noisy_src_tokens) + return noisy_src_tokens[0] + + def __len__(self): + """ + The length of the noising dataset is the length of src. + """ + return len(self.src_dataset) + + @property + def supports_prefetch(self): + return self.src_dataset.supports_prefetch + + def prefetch(self, indices): + if self.src_dataset.supports_prefetch: + self.src_dataset.prefetch(indices) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/num_samples_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/num_samples_dataset.py new file mode 100644 index 00000000..99a17495 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/num_samples_dataset.py @@ -0,0 +1,17 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from . import FairseqDataset + + +class NumSamplesDataset(FairseqDataset): + def __getitem__(self, index): + return 1 + + def __len__(self): + return 0 + + def collater(self, samples): + return sum(samples) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/numel_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/numel_dataset.py new file mode 100644 index 00000000..ac86dfd2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/numel_dataset.py @@ -0,0 +1,31 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch + +from . import BaseWrapperDataset + + +class NumelDataset(BaseWrapperDataset): + def __init__(self, dataset, reduce=False): + super().__init__(dataset) + self.reduce = reduce + + def __getitem__(self, index): + item = self.dataset[index] + if torch.is_tensor(item): + return torch.numel(item) + else: + return np.size(item) + + def __len__(self): + return len(self.dataset) + + def collater(self, samples): + if self.reduce: + return sum(samples) + else: + return torch.tensor(samples) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/offset_tokens_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/offset_tokens_dataset.py new file mode 100644 index 00000000..6fabbdcd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/offset_tokens_dataset.py @@ -0,0 +1,15 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from . import BaseWrapperDataset + + +class OffsetTokensDataset(BaseWrapperDataset): + def __init__(self, dataset, offset): + super().__init__(dataset) + self.offset = offset + + def __getitem__(self, idx): + return self.dataset[idx] + self.offset diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/pad_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/pad_dataset.py new file mode 100644 index 00000000..b512d370 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/pad_dataset.py @@ -0,0 +1,31 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.data import data_utils + +from . import BaseWrapperDataset + + +class PadDataset(BaseWrapperDataset): + def __init__(self, dataset, pad_idx, left_pad, pad_length=None): + super().__init__(dataset) + self.pad_idx = pad_idx + self.left_pad = left_pad + self.pad_length = pad_length + + def collater(self, samples): + return data_utils.collate_tokens( + samples, self.pad_idx, left_pad=self.left_pad, pad_to_length=self.pad_length + ) + + +class LeftPadDataset(PadDataset): + def __init__(self, dataset, pad_idx): + super().__init__(dataset, pad_idx, left_pad=True) + + +class RightPadDataset(PadDataset): + def __init__(self, dataset, pad_idx): + super().__init__(dataset, pad_idx, left_pad=False) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/plasma_utils.py b/PyTorch/NLP/new-Transformer/fairseq/data/plasma_utils.py new file mode 100644 index 00000000..459fb8ac --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/plasma_utils.py @@ -0,0 +1,197 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +import hashlib +import json +import subprocess +import tempfile +from typing import Hashable + +try: + import pyarrow.plasma as plasma + + PYARROW_AVAILABLE = True +except ImportError: + plasma = None + PYARROW_AVAILABLE = False + + +class PlasmaArray: + """ + Wrapper around numpy arrays that automatically moves the data to shared + memory upon serialization. This is particularly helpful when passing numpy + arrays through multiprocessing, so that data is not unnecessarily + duplicated or pickled. + """ + + def __init__(self, array): + super().__init__() + self.array = array + self.disable = array.nbytes < 134217728 # disable for arrays <128MB + self.object_id = None + self.path = None + + # variables with underscores shouldn't be pickled + self._client = None + self._server = None + self._server_tmp = None + self._plasma = None + + @property + def plasma(self): + if self._plasma is None and not self.disable: + self._plasma = plasma + return self._plasma + + def start_server(self): + if self.plasma is None or self._server is not None: + return + assert self.object_id is None + assert self.path is None + self._server_tmp = tempfile.NamedTemporaryFile() + self.path = self._server_tmp.name + self._server = subprocess.Popen( + ["plasma_store", "-m", str(int(1.05 * self.array.nbytes)), "-s", self.path] + ) + + @property + def client(self): + if self._client is None: + assert self.path is not None + self._client = self.plasma.connect(self.path, num_retries=200) + return self._client + + def __getstate__(self): + """Called on pickle load""" + if self.plasma is None: + return self.__dict__ + if self.object_id is None: + self.start_server() + self.object_id = self.client.put(self.array) + state = self.__dict__.copy() + del state["array"] + state["_client"] = None + state["_server"] = None + state["_server_tmp"] = None + state["_plasma"] = None + return state + + def __setstate__(self, state): + """Called on pickle save""" + self.__dict__.update(state) + if self.plasma is None: + return + self.array = self.client.get(self.object_id) + + def __del__(self): + if self._server is not None: + self._server.kill() + self._server = None + self._server_tmp.close() + self._server_tmp = None + + +DEFAULT_PLASMA_PATH = "/tmp/plasma" + + +class PlasmaView: + """Interface to write and read from shared memory. Whereas PlasmaArray writes to plasma on serialization, + PlasmaView writes to shared memory on instantiation.""" + + def __init__(self, array, split_path: str, hash_data: Hashable, plasma_path=None): + """ + Args: + array: numpy array to store. This can be read with ``PlasmaView().array`` + split_path: the path whence the data was read, used for hashing + hash_data: other metadata about the array that can be used to create a unique key. + as of writing, the 3 callers in ``TokenBlockDataset`` use:: + + hash_data = ((block_size, document_sep_len, str(break_mode), len(dataset)), 0|1|2) + + + """ + assert PYARROW_AVAILABLE + assert split_path is not None + if plasma_path is None: + plasma_path = DEFAULT_PLASMA_PATH + + self.path = plasma_path + self.split_path = split_path + self._client = None # Initialize lazily for pickle. plasma clients should not be deep copied or serialized. + self._n = None + + self.object_id = self.get_object_id(self.split_path, hash_data) + try: + self.client.put(array, object_id=self.object_id) + except plasma.PlasmaObjectExists: + pass + + @property + def client(self): + if self._client is None: + self._client = plasma.connect(self.path, num_retries=200) + return self._client + + @property + def array(self): + """Fetch a read only view of an np.array, stored in plasma.""" + ret = self.client.get(self.object_id) + return ret + + @staticmethod + def get_object_id(split_path: str, hash_data: Hashable): + """Returns plasma.ObjectID from hashing split_path and object_num.""" + hash = hashlib.blake2b(bytes(split_path, "utf-8"), digest_size=20) + harg = json.dumps(hash_data).encode("utf-8") + hash.update(harg) + return plasma.ObjectID(hash.digest()) + + def __getstate__(self): + """Called on pickle save""" + self.disconnect() + state = self.__dict__.copy() + assert state["_client"] is None + assert "object_id" in state + return state + + def __setstate__(self, state): + """Called on pickle load""" + self.__dict__.update(state) + + def __del__(self): + self.disconnect() + + def disconnect(self): + if self._client is not None: + self._client.disconnect() + self._client = None + + def __len__(self): + """Save reads by caching len""" + if self._n is None: + self._n = len(self.array) + return self._n + + +GB100 = (1024**3) * 100 + + +class PlasmaStore: + def __init__(self, path=DEFAULT_PLASMA_PATH, nbytes: int = GB100): + + self.server = self.start(path, nbytes) + + def __del__(self): + self.server.kill() + + @staticmethod + def start(path=DEFAULT_PLASMA_PATH, nbytes: int = GB100) -> subprocess.Popen: + if not PYARROW_AVAILABLE: + raise ImportError("please run pip install pyarrow to use --use_plasma_view") + # best practice is to allocate more space than we need. The limitation seems to be the size of /dev/shm + _server = subprocess.Popen(["plasma_store", "-m", str(nbytes), "-s", path]) + plasma.connect(path, num_retries=200) # If we can't connect we fail immediately + return _server diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/prepend_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/prepend_dataset.py new file mode 100644 index 00000000..ad74784d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/prepend_dataset.py @@ -0,0 +1,28 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch + +from . import BaseWrapperDataset + + +class PrependDataset(BaseWrapperDataset): + def __init__(self, dataset, prepend_getter, ensure_first_token_is=None): + super().__init__(dataset) + self.prepend_getter = prepend_getter + self.ensure_first_token = ensure_first_token_is + + def __getitem__(self, idx): + item = self.dataset[idx] + is_tuple = isinstance(item, tuple) + src = item[0] if is_tuple else item + + assert self.ensure_first_token is None or src[0] == self.ensure_first_token + prepend_idx = self.prepend_getter(self.dataset, idx) + assert isinstance(prepend_idx, int) + src[0] = prepend_idx + item = tuple((src,) + item[1:]) if is_tuple else src + return item diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/prepend_token_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/prepend_token_dataset.py new file mode 100644 index 00000000..fd1331f4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/prepend_token_dataset.py @@ -0,0 +1,41 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch + +from . import BaseWrapperDataset + + +class PrependTokenDataset(BaseWrapperDataset): + def __init__(self, dataset, token=None): + super().__init__(dataset) + self.token = token + if token is not None: + self._sizes = np.array(dataset.sizes) + 1 + else: + self._sizes = dataset.sizes + + def __getitem__(self, idx): + item = self.dataset[idx] + if self.token is not None: + item = torch.cat([item.new([self.token]), item]) + return item + + @property + def sizes(self): + return self._sizes + + def num_tokens(self, index): + n = self.dataset.num_tokens(index) + if self.token is not None: + n += 1 + return n + + def size(self, index): + n = self.dataset.size(index) + if self.token is not None: + n += 1 + return n diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/raw_label_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/raw_label_dataset.py new file mode 100644 index 00000000..d054904f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/raw_label_dataset.py @@ -0,0 +1,23 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +from . import FairseqDataset + + +class RawLabelDataset(FairseqDataset): + def __init__(self, labels): + super().__init__() + self.labels = labels + + def __getitem__(self, index): + return self.labels[index] + + def __len__(self): + return len(self.labels) + + def collater(self, samples): + return torch.tensor(samples) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/replace_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/replace_dataset.py new file mode 100644 index 00000000..5aac2ba9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/replace_dataset.py @@ -0,0 +1,36 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from . import BaseWrapperDataset + + +class ReplaceDataset(BaseWrapperDataset): + """Replaces tokens found in the dataset by a specified replacement token + + Args: + dataset (~torch.utils.data.Dataset): dataset to replace tokens in + replace_map(Dictionary[int,int]): map of token to replace -> replacement token + offsets (List[int]): do not replace tokens before (from left if pos, right if neg) this offset. should be + as many as the number of objects returned by the underlying dataset __getitem__ method. + """ + + def __init__(self, dataset, replace_map, offsets): + super().__init__(dataset) + assert len(replace_map) > 0 + self.replace_map = replace_map + self.offsets = offsets + + def __getitem__(self, index): + item = self.dataset[index] + is_tuple = isinstance(item, tuple) + srcs = item if is_tuple else [item] + + for offset, src in zip(self.offsets, srcs): + for k, v in self.replace_map.items(): + src_off = src[offset:] if offset >= 0 else src[:offset] + src_off.masked_fill_(src_off == k, v) + + item = srcs if is_tuple else srcs[0] + return item diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/resampling_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/resampling_dataset.py new file mode 100644 index 00000000..2d77ed79 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/resampling_dataset.py @@ -0,0 +1,139 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import numpy as np + +from fairseq.data import BaseWrapperDataset, plasma_utils + +logger = logging.getLogger(__name__) + + +class ResamplingDataset(BaseWrapperDataset): + """Randomly samples from a given dataset at each epoch. + + Sampling is done with or without replacement, depending on the "replace" + parameter. + + Optionally, the epoch size can be rescaled. This is potentially desirable + to increase per-epoch coverage of the base dataset (since sampling with + replacement means that many items in the dataset will be left out). In the + case of sampling without replacement, size_ratio should be strictly less + than 1. + + Args: + dataset (~torch.utils.data.Dataset): dataset on which to sample. + weights (List[float]): list of probability weights + (default: None, which corresponds to uniform sampling). + replace (bool): sampling mode; True for "with replacement", or False + for "without replacement" (default: True) + size_ratio (float): the ratio to subsample to; must be positive + (default: 1.0). + batch_by_size (bool): whether or not to batch by sequence length + (default: True). + seed (int): RNG seed to use (default: 0). + epoch (int): starting epoch number (default: 1). + """ + + def __init__( + self, + dataset, + weights=None, + replace=True, + size_ratio=1.0, + batch_by_size=True, + seed=0, + epoch=1, + ): + super().__init__(dataset) + + if weights is None: + self.weights = None + + else: + assert len(weights) == len(dataset) + weights_arr = np.array(weights, dtype=np.float64) + weights_arr /= weights_arr.sum() + self.weights = plasma_utils.PlasmaArray(weights_arr) + + self.replace = replace + + assert size_ratio > 0.0 + if not self.replace: + assert size_ratio < 1.0 + self.size_ratio = float(size_ratio) + self.actual_size = np.ceil(len(dataset) * self.size_ratio).astype(int) + + self.batch_by_size = batch_by_size + self.seed = seed + + self._cur_epoch = None + self._cur_indices = None + + self.set_epoch(epoch) + + def __getitem__(self, index): + return self.dataset[self._cur_indices.array[index]] + + def __len__(self): + return self.actual_size + + @property + def sizes(self): + if isinstance(self.dataset.sizes, list): + return [s[self._cur_indices.array] for s in self.dataset.sizes] + return self.dataset.sizes[self._cur_indices.array] + + def num_tokens(self, index): + return self.dataset.num_tokens(self._cur_indices.array[index]) + + def size(self, index): + return self.dataset.size(self._cur_indices.array[index]) + + def ordered_indices(self): + if self.batch_by_size: + order = [ + np.arange(len(self)), + self.sizes, + ] # No need to handle `self.shuffle == True` + return np.lexsort(order) + else: + return np.arange(len(self)) + + def prefetch(self, indices): + self.dataset.prefetch(self._cur_indices.array[indices]) + + @property + def can_reuse_epoch_itr_across_epochs(self): + return False + + def set_epoch(self, epoch): + logger.debug("ResamplingDataset.set_epoch: {}".format(epoch)) + super().set_epoch(epoch) + + if epoch == self._cur_epoch: + return + + self._cur_epoch = epoch + + # Generate a weighted sample of indices as a function of the + # random seed and the current epoch. + + rng = np.random.RandomState( + [ + 42, # magic number + self.seed % (2**32), # global seed + self._cur_epoch, # epoch index + ] + ) + self._cur_indices = plasma_utils.PlasmaArray( + rng.choice( + len(self.dataset), + self.actual_size, + replace=self.replace, + p=(None if self.weights is None else self.weights.array), + ) + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/roll_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/roll_dataset.py new file mode 100644 index 00000000..a2915eeb --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/roll_dataset.py @@ -0,0 +1,18 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +from . import BaseWrapperDataset + + +class RollDataset(BaseWrapperDataset): + def __init__(self, dataset, shifts): + super().__init__(dataset) + self.shifts = shifts + + def __getitem__(self, index): + item = self.dataset[index] + return torch.roll(item, self.shifts) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/round_robin_zip_datasets.py b/PyTorch/NLP/new-Transformer/fairseq/data/round_robin_zip_datasets.py new file mode 100644 index 00000000..2cb7447e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/round_robin_zip_datasets.py @@ -0,0 +1,160 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from collections import OrderedDict +from typing import Dict, Sequence + +import numpy as np + +from . import FairseqDataset, LanguagePairDataset + +logger = logging.getLogger(__name__) + + +class RoundRobinZipDatasets(FairseqDataset): + """Zip multiple :class:`~fairseq.data.FairseqDataset` instances together. + + Shorter datasets are repeated in a round-robin fashion to match the length + of the longest one. + + Args: + datasets (Dict[~fairseq.data.FairseqDataset]): a dictionary of + :class:`~fairseq.data.FairseqDataset` instances. + eval_key (str, optional): a key used at evaluation time that causes + this instance to pass-through batches from *datasets[eval_key]*. + """ + + def __init__(self, datasets, eval_key=None): + super().__init__() + if isinstance(datasets, dict): + datasets = OrderedDict(datasets) + assert isinstance(datasets, OrderedDict) + assert datasets, "Can't make a RoundRobinZipDatasets out of nothing" + for dataset in datasets.values(): + assert isinstance(dataset, FairseqDataset) + + self.datasets = datasets + self.eval_key = eval_key + + self.longest_dataset_key = max(datasets, key=lambda k: len(datasets[k])) + self.longest_dataset = datasets[self.longest_dataset_key] + self._ordered_indices: Dict[str, Sequence[int]] = None + + def _map_index(self, key, index): + assert ( + self._ordered_indices is not None + ), "Must call RoundRobinZipDatasets.ordered_indices() first" + o = self._ordered_indices[key] + return o[index % len(o)] + + def __getitem__(self, index): + if self.eval_key is None: + return OrderedDict( + [ + (key, dataset[self._map_index(key, index)]) + for key, dataset in self.datasets.items() + ] + ) + else: + # at evaluation time it's useful to pass-through batches from a single key + return self.datasets[self.eval_key][self._map_index(self.eval_key, index)] + + def __len__(self): + if self._ordered_indices is not None: + return len(self._ordered_indices[self.longest_dataset_key]) + return len(self.longest_dataset) + + def collater(self, samples): + """Merge a list of samples to form a mini-batch.""" + if len(samples) == 0: + return None + if self.eval_key is None: + return OrderedDict( + [ + (key, dataset.collater([sample[key] for sample in samples])) + for key, dataset in self.datasets.items() + ] + ) + else: + # at evaluation time it's useful to pass-through batches from a single key + return self.datasets[self.eval_key].collater(samples) + + def num_tokens(self, index): + """Return an example's length (number of tokens), used for batching.""" + # TODO make it configurable whether to use max() or sum() here + return max( + dataset.num_tokens(self._map_index(key, index)) + for key, dataset in self.datasets.items() + ) + + def size(self, index): + """Return an example's size as a float or tuple. This value is used when + filtering a dataset with ``--max-positions``.""" + return { + key: dataset.size(self._map_index(key, index)) + for key, dataset in self.datasets.items() + } + + def ordered_indices(self): + """Ordered indices for batching.""" + if self._ordered_indices is None: + # Call the underlying dataset's ordered_indices() here, so that we + # get the same random ordering as we would have from using the + # underlying sub-datasets directly. + self._ordered_indices = OrderedDict( + [ + (key, dataset.ordered_indices()) + for key, dataset in self.datasets.items() + ] + ) + return np.arange(len(self)) + + def filter_indices_by_size(self, indices, max_positions=None): + """ + Filter each sub-dataset independently, then update the round robin to work + on the filtered sub-datasets. + """ + + def _deep_until_language_pair(dataset): + if isinstance(dataset, LanguagePairDataset): + return dataset + if hasattr(dataset, "tgt_dataset"): + return _deep_until_language_pair(dataset.tgt_dataset) + if hasattr(dataset, "dataset"): + return _deep_until_language_pair(dataset.dataset) + raise Exception(f"Don't know how to unwrap this dataset: {dataset}") + + if not isinstance(max_positions, dict): + max_positions = {k: max_positions for k in self.datasets.keys()} + ignored_some = False + for key, dataset in self.datasets.items(): + dataset = _deep_until_language_pair(dataset) + self._ordered_indices[key], ignored = dataset.filter_indices_by_size( + self._ordered_indices[key], max_positions[key] + ) + if len(ignored) > 0: + ignored_some = True + logger.warning( + f"{len(ignored)} samples from {key} have invalid sizes and will be skipped, " + f"max_positions={max_positions[key]}, first few sample ids={ignored[:10]}" + ) + # Since we are modifying in place the _ordered_indices, + # it's not possible anymore to return valid ignored indices. + # Hopefully the extra debug information print above should be enough to debug. + # Ideally we would receive ignore_invalid_inputs so that we could have + # a proper error message. + return (np.arange(len(self)), [0] if ignored_some else []) + + @property + def supports_prefetch(self): + return all( + getattr(dataset, "supports_prefetch", False) + for dataset in self.datasets.values() + ) + + def prefetch(self, indices): + for key, dataset in self.datasets.items(): + dataset.prefetch([self._map_index(key, index) for index in indices]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/shorten_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/shorten_dataset.py new file mode 100644 index 00000000..6ebb5d88 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/shorten_dataset.py @@ -0,0 +1,78 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +from fairseq.data import data_utils + +from . import BaseWrapperDataset + + +class TruncateDataset(BaseWrapperDataset): + """Truncate a sequence by returning the first truncation_length tokens""" + + def __init__(self, dataset, truncation_length): + super().__init__(dataset) + assert truncation_length is not None + self.truncation_length = truncation_length + self.dataset = dataset + + def __getitem__(self, index): + item = self.dataset[index] + item_len = item.size(0) + if item_len > self.truncation_length: + item = item[: self.truncation_length] + return item + + @property + def sizes(self): + return np.minimum(self.dataset.sizes, self.truncation_length) + + def __len__(self): + return len(self.dataset) + + +class RandomCropDataset(TruncateDataset): + """Truncate a sequence by returning a random crop of truncation_length tokens""" + + def __init__(self, dataset, truncation_length, seed=1): + super().__init__(dataset, truncation_length) + self.seed = seed + self.epoch = 0 + + @property + def can_reuse_epoch_itr_across_epochs(self): + return True # only the crop changes, not item sizes + + def set_epoch(self, epoch, **unused): + super().set_epoch(epoch) + self.epoch = epoch + + def __getitem__(self, index): + with data_utils.numpy_seed(self.seed, self.epoch, index): + item = self.dataset[index] + item_len = item.size(0) + excess = item_len - self.truncation_length + if excess > 0: + start_idx = np.random.randint(0, excess) + item = item[start_idx : start_idx + self.truncation_length] + return item + + +def maybe_shorten_dataset( + dataset, + split, + shorten_data_split_list, + shorten_method, + tokens_per_sample, + seed, +): + truncate_split = ( + split in shorten_data_split_list.split(",") or len(shorten_data_split_list) == 0 + ) + if shorten_method == "truncate" and truncate_split: + dataset = TruncateDataset(dataset, tokens_per_sample) + elif shorten_method == "random_crop" and truncate_split: + dataset = RandomCropDataset(dataset, tokens_per_sample, seed) + return dataset diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/sort_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/sort_dataset.py new file mode 100644 index 00000000..b3890e72 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/sort_dataset.py @@ -0,0 +1,21 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np + +from . import BaseWrapperDataset + + +class SortDataset(BaseWrapperDataset): + def __init__(self, dataset, sort_order): + super().__init__(dataset) + if not isinstance(sort_order, (list, tuple)): + sort_order = [sort_order] + self.sort_order = sort_order + + assert all(len(so) == len(dataset) for so in sort_order) + + def ordered_indices(self): + return np.lexsort(self.sort_order) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/strip_token_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/strip_token_dataset.py new file mode 100644 index 00000000..cae39ba4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/strip_token_dataset.py @@ -0,0 +1,20 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from . import BaseWrapperDataset + + +class StripTokenDataset(BaseWrapperDataset): + def __init__(self, dataset, id_to_strip): + super().__init__(dataset) + self.id_to_strip = id_to_strip + + def __getitem__(self, index): + item = self.dataset[index] + while len(item) > 0 and item[-1] == self.id_to_strip: + item = item[:-1] + while len(item) > 0 and item[0] == self.id_to_strip: + item = item[1:] + return item diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/subsample_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/subsample_dataset.py new file mode 100644 index 00000000..48feaf88 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/subsample_dataset.py @@ -0,0 +1,72 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import numpy as np + +from . import BaseWrapperDataset + + +logger = logging.getLogger(__name__) + + +class SubsampleDataset(BaseWrapperDataset): + """Subsamples a given dataset by a specified ratio. Subsampling is done on the number of examples + + Args: + dataset (~torch.utils.data.Dataset): dataset to subsample + size_ratio(float): the ratio to subsample to. must be between 0 and 1 (exclusive) + """ + + def __init__(self, dataset, size_ratio, shuffle=False): + super().__init__(dataset) + assert size_ratio < 1 + self.actual_size = np.ceil(len(dataset) * size_ratio).astype(int) + self.indices = np.random.choice( + list(range(len(self.dataset))), self.actual_size, replace=False + ) + self.shuffle = shuffle + logger.info( + "subsampled dataset from {} to {} (ratio={})".format( + len(self.dataset), self.actual_size, size_ratio + ) + ) + + def __getitem__(self, index): + return self.dataset[self.indices[index]] + + def __len__(self): + return self.actual_size + + def collater(self, samples): + return self.dataset.collater(samples) + + @property + def sizes(self): + return self.dataset.sizes[self.indices] + + @property + def name(self): + return self.dataset.name + + def num_tokens(self, index): + return self.dataset.num_tokens(self.indices[index]) + + def size(self, index): + return self.dataset.size(self.indices[index]) + + def ordered_indices(self): + """Return an ordered list of indices. Batches will be constructed based + on this order.""" + if self.shuffle: + order = [np.random.permutation(len(self))] + else: + order = [np.arange(len(self))] + order.append(self.sizes) + return np.lexsort(order) + + def prefetch(self, indices): + self.dataset.prefetch(self.indices[indices]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/text_compressor.py b/PyTorch/NLP/new-Transformer/fairseq/data/text_compressor.py new file mode 100644 index 00000000..d699f2ea --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/text_compressor.py @@ -0,0 +1,58 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from enum import Enum + + +class TextCompressionLevel(Enum): + none = 0 + low = 1 + high = 2 + + +class TextCompressor(object): + def __init__( + self, level: TextCompressionLevel, max_input_byte_length: int = 2**16 + ): + self.level = level + self.max_input_length = max_input_byte_length + + def compress(self, text: str) -> bytes: + if self.level == TextCompressionLevel.low: + import zlib + + # zlib: built-in, fast + return zlib.compress(text.encode(), level=0) + elif self.level == TextCompressionLevel.high: + try: + import unishox2 + + # unishox2: optimized for short text but slower + except ImportError: + raise ImportError( + "Please install unishox2 for the text compression feature: " + "pip install unishox2-py3" + ) + assert len(text.encode()) <= self.max_input_length + return unishox2.compress(text)[0] + else: + return text.encode() + + def decompress(self, compressed: bytes) -> str: + if self.level == TextCompressionLevel.low: + import zlib + + return zlib.decompress(compressed).decode() + elif self.level == TextCompressionLevel.high: + try: + import unishox2 + except ImportError: + raise ImportError( + "Please install unishox2 for the text compression feature: " + "pip install unishox2-py3" + ) + return unishox2.decompress(compressed, self.max_input_length) + else: + return compressed.decode() diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/token_block_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/token_block_dataset.py new file mode 100644 index 00000000..a414e7ef --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/token_block_dataset.py @@ -0,0 +1,206 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch +from fairseq.data import FairseqDataset, plasma_utils +from fairseq.data.indexed_dataset import best_fitting_int_dtype +from typing import Tuple + + +class TokenBlockDataset(FairseqDataset): + """Break a Dataset of tokens into blocks. + + Args: + dataset (~torch.utils.data.Dataset): dataset to break into blocks + sizes (List[int]): sentence lengths (required for 'complete' and 'eos') + block_size (int): maximum block size (ignored in 'eos' break mode) + break_mode (str, optional): Mode used for breaking tokens. Values can + be one of: + - 'none': break tokens into equally sized blocks (up to block_size) + - 'complete': break tokens into blocks (up to block_size) such that + blocks contains complete sentences, although block_size may be + exceeded if some sentences exceed block_size + - 'complete_doc': similar to 'complete' mode, but do not + cross document boundaries + - 'eos': each block contains one sentence (block_size is ignored) + include_targets (bool, optional): return next tokens as targets + (default: False). + document_sep_len (int, optional): document separator size (required for + 'complete_doc' break mode). Typically 1 if the sentences have eos + and 0 otherwise. + """ + + def __init__( + self, + dataset, + sizes, + block_size, + pad, + eos, + break_mode=None, + include_targets=False, + document_sep_len=1, + use_plasma_view=False, + split_path=None, + plasma_path=None, + ): + + super().__init__() + self.dataset = dataset + self.pad = pad + self.eos = eos + self.include_targets = include_targets + + assert len(dataset) > 0 + + assert len(dataset) == len(sizes) + _sizes, block_to_dataset_index, slice_indices = self._build_slice_indices( + sizes, break_mode, document_sep_len, block_size + ) + if use_plasma_view: + plasma_id = (block_size, document_sep_len, str(break_mode), len(dataset)) + self._slice_indices = plasma_utils.PlasmaView( + slice_indices, split_path, (plasma_id, 0), plasma_path=plasma_path + ) + self._sizes = plasma_utils.PlasmaView( + _sizes, split_path, (plasma_id, 1), plasma_path=plasma_path + ) + self._block_to_dataset_index = plasma_utils.PlasmaView( + block_to_dataset_index, + split_path, + (plasma_id, 2), + plasma_path=plasma_path, + ) + else: + self._slice_indices = plasma_utils.PlasmaArray(slice_indices) + self._sizes = plasma_utils.PlasmaArray(_sizes) + self._block_to_dataset_index = plasma_utils.PlasmaArray( + block_to_dataset_index + ) + + @staticmethod + def _build_slice_indices( + sizes, break_mode, document_sep_len, block_size + ) -> Tuple[np.ndarray]: + """Use token_block_utils_fast to build arrays for indexing into self.dataset""" + try: + from fairseq.data.token_block_utils_fast import ( + _get_slice_indices_fast, + _get_block_to_dataset_index_fast, + ) + except ImportError: + raise ImportError( + "Please build Cython components with: `pip install --editable .` " + "or `python setup.py build_ext --inplace`" + ) + + if isinstance(sizes, list): + sizes = np.array(sizes, dtype=np.int64) + else: + if torch.is_tensor(sizes): + sizes = sizes.numpy() + sizes = sizes.astype(np.int64) + + break_mode = break_mode if break_mode is not None else "none" + + # For "eos" break-mode, block_size is not required parameters. + if break_mode == "eos" and block_size is None: + block_size = 0 + + slice_indices = _get_slice_indices_fast( + sizes, str(break_mode), block_size, document_sep_len + ) + _sizes = slice_indices[:, 1] - slice_indices[:, 0] + + # build index mapping block indices to the underlying dataset indices + if break_mode == "eos": + # much faster version for eos break mode + block_to_dataset_index = np.stack( + [ + np.arange(len(sizes)), # starting index in dataset + np.zeros( + len(sizes), dtype=np.compat.long + ), # starting offset within starting index + np.arange(len(sizes)), # ending index in dataset + ], + 1, + ) + else: + block_to_dataset_index = _get_block_to_dataset_index_fast( + sizes, + slice_indices, + ) + size_dtype = np.uint16 if block_size < 65535 else np.uint32 + num_tokens = slice_indices[-1].max() + slice_indices_dtype = best_fitting_int_dtype(num_tokens) + slice_indices = slice_indices.astype(slice_indices_dtype) + _sizes = _sizes.astype(size_dtype) + block_to_dataset_index = block_to_dataset_index.astype(slice_indices_dtype) + return _sizes, block_to_dataset_index, slice_indices + + @property + def slice_indices(self): + return self._slice_indices.array + + @property + def sizes(self): + return self._sizes.array + + @property + def block_to_dataset_index(self): + return self._block_to_dataset_index.array + + def attr(self, attr: str, index: int): + start_ds_idx, _, _ = self.block_to_dataset_index[index] + return self.dataset.attr(attr, start_ds_idx) + + def __getitem__(self, index): + start_ds_idx, start_offset, end_ds_idx = self.block_to_dataset_index[index] + + buffer = torch.cat( + [self.dataset[idx] for idx in range(start_ds_idx, end_ds_idx + 1)] + ) + slice_s, slice_e = self.slice_indices[index] + length = slice_e - slice_s + s, e = start_offset, start_offset + length + item = buffer[s:e] + + if self.include_targets: + # *target* is the original sentence (=item) + # *source* is shifted right by 1 (maybe left-padded with eos) + # *past_target* is shifted right by 2 (left-padded as needed) + if s == 0: + source = torch.cat([item.new([self.eos]), buffer[0 : e - 1]]) + past_target = torch.cat( + [item.new([self.pad, self.eos]), buffer[0 : e - 2]] + ) + else: + source = buffer[s - 1 : e - 1] + if s == 1: + past_target = torch.cat([item.new([self.eos]), buffer[0 : e - 2]]) + else: + past_target = buffer[s - 2 : e - 2] + + return source, item, past_target + + return item + + def __len__(self): + return len(self.slice_indices) + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def prefetch(self, indices): + self.dataset.prefetch( + { + ds_idx + for index in indices + for start_ds_idx, _, end_ds_idx in [self.block_to_dataset_index[index]] + for ds_idx in range(start_ds_idx, end_ds_idx + 1) + } + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/token_block_utils_fast.pyx b/PyTorch/NLP/new-Transformer/fairseq/data/token_block_utils_fast.pyx new file mode 100644 index 00000000..08af4f30 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/token_block_utils_fast.pyx @@ -0,0 +1,187 @@ +# cython: language_level=3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch +from itertools import chain +from libc.math cimport ceil + +cimport cython +cimport numpy as np + +from libc.stdint cimport int32_t, int64_t + +DTYPE = np.int64 +ctypedef int64_t DTYPE_t + + +@cython.boundscheck(False) +@cython.wraparound(False) +@cython.nonecheck(False) +cdef np.ndarray[DTYPE_t, ndim=2] _get_slice_indices_none_mode(np.ndarray[DTYPE_t, ndim=1] sizes, int block_size): + cdef DTYPE_t total_size = sizes.sum() + cdef DTYPE_t length = ceil(total_size / block_size) + cdef np.ndarray[DTYPE_t, ndim=2] slice_indices = np.zeros([length, 2], dtype=DTYPE) + cdef DTYPE_t[:, :] slice_indices_view = slice_indices + cdef DTYPE_t i + cdef DTYPE_t start + cdef DTYPE_t end + for i in range(length): + start = i * block_size + end = min(start + block_size, total_size) + slice_indices_view[i][0] = start + slice_indices_view[i][1] = end + return slice_indices + + +cdef np.ndarray[DTYPE_t, ndim=2] _fast_convert_to_np_array(list list_of_list): + """ + Faster function to convert DTYPE_t list of list. + Only fast when there are huge number of rows and low number of columns. + """ + cdef np.ndarray[DTYPE_t, ndim=1] flat = np.fromiter(chain.from_iterable(list_of_list), DTYPE, -1) + return flat.reshape((len(list_of_list), -1)) + + +@cython.boundscheck(False) +@cython.wraparound(False) +@cython.nonecheck(False) +cpdef np.ndarray[DTYPE_t, ndim=2] _get_slice_indices_fast(np.ndarray[DTYPE_t, ndim=1] sizes, str break_mode, int block_size, int document_sep_len): + cdef DTYPE_t tok_idx = 0 + cdef DTYPE_t sz_idx = 0 + cdef DTYPE_t curr_size = 0 + cdef DTYPE_t i = 0 + cdef DTYPE_t length + cdef DTYPE_t total_size + cdef DTYPE_t[:] sizes_view = sizes + cdef np.ndarray[DTYPE_t, ndim=2] slice_indices + cdef list slice_indices_list = [] + + if break_mode is None or break_mode == 'none': + slice_indices = _get_slice_indices_none_mode(sizes, block_size) + elif break_mode == 'complete': + while sz_idx < len(sizes_view): + if curr_size + sizes_view[sz_idx] <= block_size or curr_size == 0: + curr_size += sizes_view[sz_idx] + sz_idx += 1 + else: + slice_indices_list.append((tok_idx, tok_idx + curr_size)) + tok_idx += curr_size + curr_size = 0 + if curr_size > 0: + slice_indices_list.append((tok_idx, tok_idx + curr_size)) + slice_indices = _fast_convert_to_np_array(slice_indices_list) + elif break_mode == 'complete_doc': + while sz_idx < len(sizes_view): + if ( + (curr_size + sizes_view[sz_idx] <= block_size or curr_size == 0) + # an empty sentence indicates end-of-document: + and sizes_view[sz_idx] != document_sep_len + ): + curr_size += sizes_view[sz_idx] + sz_idx += 1 + else: + # Only keep non-empty documents. + if curr_size > 1: + slice_indices_list.append((tok_idx, tok_idx + curr_size)) + tok_idx += curr_size + curr_size = 0 + if sizes_view[sz_idx] == document_sep_len: + tok_idx += sizes_view[sz_idx] + sz_idx += 1 + if curr_size > 1: + slice_indices_list.append((tok_idx, tok_idx + curr_size)) + slice_indices = _fast_convert_to_np_array(slice_indices_list) + elif break_mode == 'eos': + slice_indices = np.zeros((len(sizes), 2), dtype=DTYPE) + cumsum = sizes.cumsum(axis=0) + slice_indices[1:, 0] = cumsum[:cumsum.shape[0] - 1] + slice_indices[:, 1] = cumsum + else: + raise ValueError('Invalid break_mode: ' + break_mode) + return slice_indices + + +@cython.boundscheck(False) +@cython.wraparound(False) +@cython.nonecheck(False) +cpdef np.ndarray[DTYPE_t, ndim=2] _get_block_to_dataset_index_fast(np.ndarray[DTYPE_t, ndim=1] sizes, np.ndarray[DTYPE_t, ndim=2] slice_indices): + cdef DTYPE_t start_ds_idx + cdef DTYPE_t start_offset + cdef DTYPE_t end_ds_idx + cdef DTYPE_t i + cdef DTYPE_t s + cdef DTYPE_t e + cdef DatasetSearcher ds = DatasetSearcher(sizes) + cdef np.ndarray[DTYPE_t, ndim=2] block_to_dataset_index = np.zeros([len(slice_indices), 3], dtype=DTYPE) + cdef DTYPE_t[:, :] block_to_dataset_index_view = block_to_dataset_index + cdef DTYPE_t[:, :] slice_indices_view = slice_indices + cdef Py_ssize_t x_max = slice_indices.shape[0] + + for i in range(x_max): + s = slice_indices_view[i][0] + e = slice_indices_view[i][1] + ds.seek(s) + start_ds_idx = ds.current_index + start_offset = ds.current_offset + if e <= s: + end_ds_idx = start_ds_idx + else: + ds.seek(e - 1) + end_ds_idx = ds.current_index + block_to_dataset_index_view[i][0] = start_ds_idx # starting index in dataset + block_to_dataset_index_view[i][1] = start_offset # starting offset within starting index + block_to_dataset_index_view[i][2] = end_ds_idx # ending index in dataset + return block_to_dataset_index + + +cdef class DatasetSearcher(object): + """Helper for mapping "flat" indices to indices and offsets in an + underlying dataset.""" + cdef DTYPE_t current_i + cdef DTYPE_t current_offset + cdef DTYPE_t current_index + cdef DTYPE_t[:] sizes + + def __init__(self, DTYPE_t[:] sizes): + self.sizes = sizes + self.reset() + + cdef reset(self): + self.current_offset = 0 # offset within current index in underlying dataset + self.current_i = 0 # "flat" index + self.current_index = 0 # index in underlying dataset + + @cython.boundscheck(False) + @cython.wraparound(False) + @cython.nonecheck(False) + cdef int step(self, DTYPE_t i): + cdef DTYPE_t to_consume + cdef DTYPE_t remaining + if i < self.current_i: + self.reset() + if i > self.current_i: + to_consume = i - self.current_i + remaining = self.sizes[self.current_index] - self.current_offset + if remaining > to_consume: + self.current_offset += to_consume + self.current_i += to_consume + else: + assert remaining >= 0 + self.current_i += remaining + self.current_index += 1 + self.current_offset = 0 + return 1 + return 0 + + @cython.boundscheck(False) + @cython.wraparound(False) + @cython.nonecheck(False) + cdef seek(self, DTYPE_t i): + cdef int not_done = 1 + while not_done == 1: + not_done = self.step(i) + assert self.current_i == i diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_concat_langpair_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_concat_langpair_dataset.py new file mode 100644 index 00000000..638bd1a3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_concat_langpair_dataset.py @@ -0,0 +1,139 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch +from torch.utils.data.dataloader import default_collate + +from fairseq.data import ConcatDataset + +logger = logging.getLogger(__name__) + + +class TransformEosConcatLangPairDataset(ConcatDataset): + """ + It is a combination of TransformEosLangPairDataset and ConcatDataset for multiple LangPairDataset datasets. + Assume all datasets share the same src_eos, tgt_bos, left_pad_source and left_pad_target + """ + + def __init__( + self, + datasets, + src_eos, + tgt_bos, + new_src_eos=None, + new_tgt_bos=None, + ): + super().__init__(datasets) + if new_src_eos is not None: + assert len(new_src_eos) == len(datasets) + else: + new_src_eos = [] + if new_tgt_bos is not None: + assert len(new_tgt_bos) == len(datasets) + else: + new_tgt_bos = [] + self.src_eos = src_eos + self.tgt_bos = tgt_bos + self.new_src_eos = ( + torch.LongTensor(new_src_eos).cpu() if len(new_src_eos) > 0 else [] + ) + self.new_tgt_bos = ( + torch.LongTensor(new_tgt_bos).cpu() if len(new_tgt_bos) > 0 else [] + ) + self.left_pad_source = self.is_left_pad_source(datasets) + self.left_pad_target = self.is_left_pad_target(datasets) + self.pad_idx = self.src_dict_pad() + + def src_dict_pad(self): + if hasattr(self.datasets[0], "src_dict"): + return self.datasets[0].src_dict.pad() + if hasattr(self.datasets[0], "dataset"): + return self.datasets[0].dataset.src_dict.pad() + raise NotImplementedError("No src_dict is found") + + def __getitem__(self, idx): + dataset_idx, sample_idx = self._get_dataset_and_sample_index(idx) + return dataset_idx, self.datasets[dataset_idx][sample_idx] + + def is_left_pad_source(self, datasets): + def _left_pad_source(ds): + if hasattr(ds, "left_pad_source"): + return ds.left_pad_source + if hasattr(ds, "dataset"): + return _left_pad_source(ds.dataset) + logger.warn(f"{type(ds)} has no left_pad_source, using default True") + return True + + left_pad_source = _left_pad_source(datasets[0]) + for ds in datasets: + if left_pad_source != _left_pad_source(ds): + raise ValueError("Different left_pad_source setting detected!") + return left_pad_source + + def is_left_pad_target(self, datasets): + def _left_pad_target(ds): + if hasattr(ds, "left_pad_target"): + return ds.left_pad_target + if hasattr(ds, "dataset"): + return _left_pad_target(ds.dataset) + logger.warn(f"{type(ds)} has no left_pad_target, using default False") + return False + + left_pad_target = _left_pad_target(datasets[0]) + for ds in datasets: + if left_pad_target != _left_pad_target(ds): + raise ValueError("Different left_pad_target setting detected!") + return left_pad_target + + def collater(self, samples, **extra_args): + if len(samples) == 0: + return samples + + dataset_ids = [s[0] for s in samples] + samples = [s[1] for s in samples] + + if hasattr(self.datasets[0], "collater"): + samples = self.datasets[0].collater(samples, **extra_args) + else: + samples = default_collate(samples, **extra_args) + + if len(self.new_src_eos) > 0: + if self.left_pad_source: + assert ( + samples["net_input"]["src_tokens"][:, -1] != self.src_eos + ).sum() == 0 + samples["net_input"]["src_tokens"][:, -1] = self.new_src_eos[ + dataset_ids + ] + + else: + eos_idx = samples["net_input"]["src_lengths"] - 1 + assert ( + samples["net_input"]["src_tokens"][ + torch.arange(eos_idx.size(0)), eos_idx + ] + != self.src_eos + ).sum() == 0 + samples["net_input"]["src_tokens"].scatter_( + 1, eos_idx.view(-1, 1), self.new_src_eos[dataset_ids].view(-1, 1) + ) + + if len(self.new_tgt_bos) > 0 and "prev_output_tokens" in samples["net_input"]: + if self.left_pad_target: + # TODO: support different padding direction on target side + raise NotImplementedError( + "TransformEosLangPairDataset does not implement --left-pad-target True option" + ) + else: + assert ( + samples["net_input"]["prev_output_tokens"][:, 0] != self.tgt_bos + ).sum() == 0 + samples["net_input"]["prev_output_tokens"][:, 0] = self.new_tgt_bos[ + dataset_ids + ] + + return samples diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_dataset.py new file mode 100644 index 00000000..fb14ff01 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_dataset.py @@ -0,0 +1,120 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +from . import FairseqDataset + + +class TransformEosDataset(FairseqDataset): + """A :class:`~fairseq.data.FairseqDataset` wrapper that appends/prepends/strips EOS. + + Note that the transformation is applied in :func:`collater`. + + Args: + dataset (~fairseq.data.FairseqDataset): dataset to wrap + eos (int): index of the end-of-sentence symbol + append_eos_to_src (bool, optional): append EOS to the end of src + remove_eos_from_src (bool, optional): remove EOS from the end of src + append_eos_to_tgt (bool, optional): append EOS to the end of tgt + remove_eos_from_tgt (bool, optional): remove EOS from the end of tgt + """ + + def __init__( + self, + dataset, + eos, + append_eos_to_src=False, + remove_eos_from_src=False, + append_eos_to_tgt=False, + remove_eos_from_tgt=False, + has_target=True, + ): + if not isinstance(dataset, FairseqDataset): + raise ValueError("dataset must be an instance of FairseqDataset") + if append_eos_to_src and remove_eos_from_src: + raise ValueError("cannot combine append_eos_to_src and remove_eos_from_src") + if append_eos_to_tgt and remove_eos_from_tgt: + raise ValueError("cannot combine append_eos_to_tgt and remove_eos_from_tgt") + + self.dataset = dataset + self.eos = torch.LongTensor([eos]) + self.append_eos_to_src = append_eos_to_src + self.remove_eos_from_src = remove_eos_from_src + self.append_eos_to_tgt = append_eos_to_tgt + self.remove_eos_from_tgt = remove_eos_from_tgt + self.has_target = has_target + + # precompute how we should adjust the reported sizes + self._src_delta = 0 + self._src_delta += 1 if append_eos_to_src else 0 + self._src_delta -= 1 if remove_eos_from_src else 0 + self._tgt_delta = 0 + self._tgt_delta += 1 if append_eos_to_tgt else 0 + self._tgt_delta -= 1 if remove_eos_from_tgt else 0 + + self._checked_src = False + self._checked_tgt = False + + def _check_src(self, src, expect_eos): + if not self._checked_src: + assert (src[-1] == self.eos[0]) == expect_eos + self._checked_src = True + + def _check_tgt(self, tgt, expect_eos): + if self.has_target and not self._checked_tgt: + assert (tgt[-1] == self.eos[0]) == expect_eos + self._checked_tgt = True + + def __getitem__(self, index): + return self.dataset[index] + + def __len__(self): + return len(self.dataset) + + def collater(self, samples): + def transform(item): + if self.append_eos_to_src: + self.eos = self.eos.to(device=item["source"].device) + self._check_src(item["source"], expect_eos=False) + item["source"] = torch.cat([item["source"], self.eos]) + if self.remove_eos_from_src: + self.eos = self.eos.to(device=item["source"].device) + self._check_src(item["source"], expect_eos=True) + item["source"] = item["source"][:-1] + if self.append_eos_to_tgt: + self.eos = self.eos.to(device=item["target"].device) + self._check_tgt(item["target"], expect_eos=False) + item["target"] = torch.cat([item["target"], self.eos]) + if self.remove_eos_from_tgt: + self.eos = self.eos.to(device=item["target"].device) + self._check_tgt(item["target"], expect_eos=True) + item["target"] = item["target"][:-1] + return item + + samples = list(map(transform, samples)) + return self.dataset.collater(samples) + + def num_tokens(self, index): + return self.dataset.num_tokens(index) + + def size(self, index): + if self.has_target: + src_len, tgt_len = self.dataset.size(index) + return (src_len + self._src_delta, tgt_len + self._tgt_delta) + else: + return self.dataset.size(index) + + def ordered_indices(self): + # NOTE: we assume that the ordering does not change based on the + # addition or removal of eos + return self.dataset.ordered_indices() + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def prefetch(self, indices): + return self.dataset.prefetch(indices) diff --git a/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_lang_pair_dataset.py b/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_lang_pair_dataset.py new file mode 100644 index 00000000..d8b21090 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/data/transform_eos_lang_pair_dataset.py @@ -0,0 +1,113 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from typing import Optional + +import torch + +from . import FairseqDataset + + +class TransformEosLangPairDataset(FairseqDataset): + """A :class:`~fairseq.data.FairseqDataset` wrapper that transform bos on + collated samples of language pair dataset. + + Note that the transformation is applied in :func:`collater`. + + Args: + dataset (~fairseq.data.FairseqDataset): dataset that collates sample into + LanguagePairDataset schema + src_eos (int): original source end-of-sentence symbol index to be replaced + new_src_eos (int, optional): new end-of-sentence symbol index to replace source eos symbol + tgt_bos (int, optional): original target beginning-of-sentence symbol index to be replaced + new_tgt_bos (int, optional): new beginning-of-sentence symbol index to replace at the + beginning of 'prev_output_tokens' + """ + + def __init__( + self, + dataset: FairseqDataset, + src_eos: int, + new_src_eos: Optional[int] = None, + tgt_bos: Optional[int] = None, + new_tgt_bos: Optional[int] = None, + ): + self.dataset = dataset + self.src_eos = src_eos + self.new_src_eos = new_src_eos + self.tgt_bos = tgt_bos + self.new_tgt_bos = new_tgt_bos + + def __getitem__(self, index): + return self.dataset[index] + + def __len__(self): + return len(self.dataset) + + def collater(self, samples, **extra_args): + samples = self.dataset.collater(samples, **extra_args) + if len(samples) == 0: + return samples + + if "net_input" not in samples: + return samples + + if self.new_src_eos is not None: + if self.dataset.left_pad_source: + assert ( + samples["net_input"]["src_tokens"][:, -1] != self.src_eos + ).sum() == 0 + samples["net_input"]["src_tokens"][:, -1] = self.new_src_eos + else: + eos_idx = samples["net_input"]["src_lengths"] - 1 + assert ( + samples["net_input"]["src_tokens"][ + torch.arange(eos_idx.size(0)), eos_idx + ] + != self.src_eos + ).sum() == 0 + eos_idx = eos_idx.resize_(len(samples["net_input"]["src_lengths"]), 1) + samples["net_input"]["src_tokens"].scatter_( + 1, eos_idx, self.new_src_eos + ) + + if ( + self.new_tgt_bos is not None + and "prev_output_tokens" in samples["net_input"] + ): + if self.dataset.left_pad_target: + # TODO: support different padding direction on target side + raise NotImplementedError( + "TransformEosLangPairDataset does not implement --left-pad-target True option" + ) + else: + assert ( + samples["net_input"]["prev_output_tokens"][:, 0] != self.tgt_bos + ).sum() == 0 + samples["net_input"]["prev_output_tokens"][:, 0] = self.new_tgt_bos + + return samples + + def num_tokens(self, index): + return self.dataset.num_tokens(index) + + def size(self, index): + return self.dataset.size(index) + + @property + def sizes(self): + # dataset.sizes can be a dynamically computed sizes: + return self.dataset.sizes + + def ordered_indices(self): + return self.dataset.ordered_indices() + + @property + def supports_prefetch(self): + return getattr(self.dataset, "supports_prefetch", False) + + def prefetch(self, indices): + return self.dataset.prefetch(indices) diff --git a/PyTorch/NLP/new-Transformer/fairseq/dataclass/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/dataclass/__init__.py new file mode 100644 index 00000000..25408d28 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/dataclass/__init__.py @@ -0,0 +1,13 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .configs import FairseqDataclass +from .constants import ChoiceEnum + + +__all__ = [ + "FairseqDataclass", + "ChoiceEnum", +] diff --git a/PyTorch/NLP/new-Transformer/fairseq/dataclass/configs.py b/PyTorch/NLP/new-Transformer/fairseq/dataclass/configs.py new file mode 100644 index 00000000..3079101d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/dataclass/configs.py @@ -0,0 +1,1124 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import os +import sys +from dataclasses import _MISSING_TYPE, dataclass, field +from typing import Any, List, Optional + +import torch +from omegaconf import II, MISSING + +from fairseq.dataclass.constants import ( + DATASET_IMPL_CHOICES, + DDP_BACKEND_CHOICES, + DDP_COMM_HOOK_CHOICES, + GENERATION_CONSTRAINTS_CHOICES, + GENERATION_DECODING_FORMAT_CHOICES, + LOG_FORMAT_CHOICES, + PIPELINE_CHECKPOINT_CHOICES, + PRINT_ALIGNMENT_CHOICES, + ZERO_SHARDING_CHOICES, +) + + +@dataclass +class FairseqDataclass: + """fairseq base dataclass that supported fetching attributes and metas""" + + _name: Optional[str] = None + + @staticmethod + def name(): + return None + + def _get_all_attributes(self) -> List[str]: + return [k for k in self.__dataclass_fields__.keys()] + + def _get_meta( + self, attribute_name: str, meta: str, default: Optional[Any] = None + ) -> Any: + return self.__dataclass_fields__[attribute_name].metadata.get(meta, default) + + def _get_name(self, attribute_name: str) -> str: + return self.__dataclass_fields__[attribute_name].name + + def _get_default(self, attribute_name: str) -> Any: + if hasattr(self, attribute_name): + if str(getattr(self, attribute_name)).startswith("${"): + return str(getattr(self, attribute_name)) + elif str(self.__dataclass_fields__[attribute_name].default).startswith( + "${" + ): + return str(self.__dataclass_fields__[attribute_name].default) + elif ( + getattr(self, attribute_name) + != self.__dataclass_fields__[attribute_name].default + ): + return getattr(self, attribute_name) + + f = self.__dataclass_fields__[attribute_name] + if not isinstance(f.default_factory, _MISSING_TYPE): + return f.default_factory() + return f.default + + def _get_type(self, attribute_name: str) -> Any: + return self.__dataclass_fields__[attribute_name].type + + def _get_help(self, attribute_name: str) -> Any: + return self._get_meta(attribute_name, "help") + + def _get_argparse_const(self, attribute_name: str) -> Any: + return self._get_meta(attribute_name, "argparse_const") + + def _get_argparse_alias(self, attribute_name: str) -> Any: + return self._get_meta(attribute_name, "argparse_alias") + + def _get_choices(self, attribute_name: str) -> Any: + return self._get_meta(attribute_name, "choices") + + @classmethod + def from_namespace(cls, args): + if isinstance(args, cls): + return args + else: + config = cls() + for k in config.__dataclass_fields__.keys(): + if k.startswith("_"): + # private member, skip + continue + if hasattr(args, k): + setattr(config, k, getattr(args, k)) + + return config + + +@dataclass +class CommonConfig(FairseqDataclass): + # This is the core dataclass including common parameters shared by all different jobs. Please append your params to other dataclasses if they were + # used for a particular purpose or task, such as those dedicated for `distributed training`, `optimization`, etc. + no_progress_bar: bool = field( + default=False, metadata={"help": "disable progress bar"} + ) + log_interval: int = field( + default=100, + metadata={ + "help": "log progress every N batches (when progress bar is disabled)" + }, + ) + log_format: Optional[LOG_FORMAT_CHOICES] = field( + default=None, metadata={"help": "log format to use"} + ) + log_file: Optional[str] = field( + default=None, metadata={"help": "log file to copy metrics to."} + ) + aim_repo: Optional[str] = field( + default=None, + metadata={"help": "path to Aim repository"}, + ) + aim_run_hash: Optional[str] = field( + default=None, + metadata={ + "help": "Aim run hash. If skipped, creates or continues run " + "based on save_dir" + }, + ) + tensorboard_logdir: Optional[str] = field( + default=None, + metadata={ + "help": "path to save logs for tensorboard, should match --logdir " + "of running tensorboard (default: no tensorboard logging)" + }, + ) + wandb_project: Optional[str] = field( + default=None, + metadata={"help": "Weights and Biases project name to use for logging"}, + ) + azureml_logging: Optional[bool] = field( + default=False, + metadata={"help": "Log scalars to AzureML context"}, + ) + seed: int = field( + default=1, metadata={"help": "pseudo random number generator seed"} + ) + cpu: bool = field(default=False, metadata={"help": "use CPU instead of CUDA"}) + tpu: bool = field(default=False, metadata={"help": "use TPU instead of CUDA"}) + bf16: bool = field(default=False, metadata={"help": "use bfloat16; implies --tpu"}) + memory_efficient_bf16: bool = field( + default=False, + metadata={ + "help": "use a memory-efficient version of BF16 training; implies --bf16" + }, + ) + fp16: bool = field(default=False, metadata={"help": "use FP16"}) + memory_efficient_fp16: bool = field( + default=False, + metadata={ + "help": "use a memory-efficient version of FP16 training; implies --fp16" + }, + ) + fp16_no_flatten_grads: bool = field( + default=False, metadata={"help": "don't flatten FP16 grads tensor"} + ) + fp16_init_scale: int = field( + default=2**7, metadata={"help": "default FP16 loss scale"} + ) + fp16_scale_window: Optional[int] = field( + default=None, + metadata={"help": "number of updates before increasing loss scale"}, + ) + fp16_scale_tolerance: float = field( + default=0.0, + metadata={ + "help": "pct of updates that can overflow before decreasing the loss scale" + }, + ) + on_cpu_convert_precision: bool = field( + default=False, + metadata={ + "help": "if set, the floating point conversion to fp16/bf16 runs on CPU. " + "This reduces bus transfer time and GPU memory usage." + }, + ) + min_loss_scale: float = field( + default=1e-4, + metadata={ + "help": "minimum FP16/AMP loss scale, after which training is stopped" + }, + ) + threshold_loss_scale: Optional[float] = field( + default=None, metadata={"help": "threshold FP16 loss scale from below"} + ) + amp: bool = field(default=False, metadata={"help": "use automatic mixed precision"}) + amp_batch_retries: int = field( + default=2, + metadata={ + "help": "number of retries of same batch after reducing loss scale with AMP" + }, + ) + amp_init_scale: int = field( + default=2**7, metadata={"help": "default AMP loss scale"} + ) + amp_scale_window: Optional[int] = field( + default=None, + metadata={"help": "number of updates before increasing AMP loss scale"}, + ) + user_dir: Optional[str] = field( + default=None, + metadata={ + "help": "path to a python module containing custom extensions (tasks and/or architectures)" + }, + ) + empty_cache_freq: int = field( + default=0, + metadata={"help": "how often to clear the PyTorch CUDA cache (0 to disable)"}, + ) + all_gather_list_size: int = field( + default=16384, + metadata={"help": "number of bytes reserved for gathering stats from workers"}, + ) + model_parallel_size: int = field( + default=1, metadata={"help": "total number of GPUs to parallelize model over"} + ) + quantization_config_path: Optional[str] = field( + default=None, metadata={"help": "path to quantization config file"} + ) + profile: bool = field( + default=False, metadata={"help": "enable autograd profiler emit_nvtx"} + ) + reset_logging: bool = field( + default=False, + metadata={ + "help": "when using Hydra, reset the logging at the beginning of training" + }, + ) + suppress_crashes: bool = field( + default=False, + metadata={ + "help": "suppress crashes when training with the hydra_train entry point so that the " + "main method can return a value (useful for sweeps)" + }, + ) + use_plasma_view: bool = field( + default=False, metadata={"help": "Store indices and sizes in shared memory"} + ) + plasma_path: Optional[str] = field( + default="/tmp/plasma", + metadata={ + "help": "path to run plasma_store, defaults to /tmp/plasma. Paths outside /tmp tend to fail." + }, + ) + + +@dataclass +class DistributedTrainingConfig(FairseqDataclass): + distributed_world_size: int = field( + default=max(1, torch.cuda.device_count()), + metadata={ + "help": "total number of GPUs across all nodes (default: all visible GPUs)" + }, + ) + distributed_num_procs: Optional[int] = field( + default=max(1, torch.cuda.device_count()), + metadata={ + "help": "total number of processes to fork (default: all visible GPUs)" + }, + ) + distributed_rank: Optional[int] = field( + default=0, metadata={"help": "rank of the current worker"} + ) + distributed_backend: str = field( + default="nccl", metadata={"help": "distributed backend"} + ) + distributed_init_method: Optional[str] = field( + default=None, + metadata={ + "help": "typically tcp://hostname:port that will be used to " + "establish initial connetion" + }, + ) + distributed_port: int = field( + default=-1, + metadata={ + "help": "port number (not required if using --distributed-init-method)" + }, + ) + device_id: int = field( + default=os.getenv("LOCAL_RANK", 0), + metadata={ + "help": "which GPU to use (by default looks for $LOCAL_RANK, usually configured automatically)", + "argparse_alias": "--local_rank", + }, + ) + distributed_no_spawn: bool = field( + default=False, + metadata={ + "help": "do not spawn multiple processes even if multiple GPUs are visible" + }, + ) + ddp_backend: DDP_BACKEND_CHOICES = field( + default="pytorch_ddp", metadata={"help": "DistributedDataParallel backend"} + ) + ddp_comm_hook: DDP_COMM_HOOK_CHOICES = field( + default="none", metadata={"help": "communication hook"} + ) + bucket_cap_mb: int = field( + default=25, metadata={"help": "bucket size for reduction"} + ) + fix_batches_to_gpus: bool = field( + default=False, + metadata={ + "help": "don't shuffle batches between GPUs; this reduces overall " + "randomness and may affect precision but avoids the cost of re-reading the data" + }, + ) + find_unused_parameters: bool = field( + default=False, + metadata={ + "help": "disable unused parameter detection (not applicable to " + "--ddp-backend=legacy_ddp)" + }, + ) + gradient_as_bucket_view: bool = field( + default=False, + metadata={ + "help": "when set to True, gradients will be views pointing to different offsets of allreduce communication buckets. This can reduce peak memory usage, where the saved memory size will be equal to the total gradients size. " + "--gradient-as-bucket-view=gradient_as_bucket_view)" + }, + ) + fast_stat_sync: bool = field( + default=False, + metadata={"help": "[deprecated] this is now defined per Criterion"}, + ) + heartbeat_timeout: int = field( + default=-1, + metadata={ + "help": "kill the job if no progress is made in N seconds; " + "set to -1 to disable" + }, + ) + broadcast_buffers: bool = field( + default=False, + metadata={ + "help": "Copy non-trainable parameters between GPUs, such as " + "batchnorm population statistics" + }, + ) + slowmo_momentum: Optional[float] = field( + default=None, + metadata={ + "help": "SlowMo momentum term; by default use 0.0 for 16 GPUs, " + "0.2 for 32 GPUs; 0.5 for 64 GPUs, 0.6 for > 64 GPUs" + }, + ) + slowmo_base_algorithm: str = field( + default="localsgd", + metadata={ + "help": "Base algorithm. Either 'localsgd' or 'sgp'. Please refer " + "to the documentation of 'slowmo_base_algorithm' parameter in " + "https://fairscale.readthedocs.io/en/latest/api/experimental/nn/slowmo_ddp.html " + "for more details" + }, + ) + localsgd_frequency: int = field( + default=3, metadata={"help": "Local SGD allreduce frequency"} + ) + nprocs_per_node: int = field( + default=max(1, torch.cuda.device_count()), + metadata={ + "help": "number of GPUs in each node. An allreduce operation across GPUs in " + "a node is very fast. Hence, we do allreduce across GPUs in a node, " + "and gossip across different nodes" + }, + ) + pipeline_model_parallel: bool = field( + default=False, + metadata={"help": "if set, use pipeline model parallelism across GPUs"}, + ) + pipeline_balance: Optional[str] = field( + default=None, + metadata={ + "help": "partition the model into N_K pieces, where each piece " + "contains N_i layers. The sum(args.pipeline_balance) " + "should equal the total number of layers in the model" + }, + ) + pipeline_devices: Optional[str] = field( + default=None, + metadata={ + "help": "a list of device indices indicating which device to place " + "each of the N_K partitions. The length of this list should " + "equal the length of the --pipeline-balance argument" + }, + ) + pipeline_chunks: Optional[int] = field( + default=0, metadata={"help": "microbatch count for pipeline model parallelism"} + ) + pipeline_encoder_balance: Optional[str] = field( + default=None, + metadata={ + "help": "partition the pipeline parallel encoder into N_K pieces, where each piece " + "contains N_i layers. The sum(args.pipeline_encoder_balance) " + "should equal the total number of encoder layers in the model" + }, + ) + pipeline_encoder_devices: Optional[str] = field( + default=None, + metadata={ + "help": "a list of device indices indicating which device to place " + "each of the N_K partitions. The length of this list should " + "equal the length of the --pipeline-encoder-balance argument" + }, + ) + pipeline_decoder_balance: Optional[str] = field( + default=None, + metadata={ + "help": "partition the pipeline parallel decoder into N_K pieces, where each piece " + "contains N_i layers. The sum(args.pipeline_decoder_balance) " + "should equal the total number of decoder layers in the model" + }, + ) + pipeline_decoder_devices: Optional[str] = field( + default=None, + metadata={ + "help": "a list of device indices indicating which device to place " + "each of the N_K partitions. The length of this list should " + "equal the length of the --pipeline-decoder-balance argument" + }, + ) + pipeline_checkpoint: PIPELINE_CHECKPOINT_CHOICES = field( + default="never", + metadata={"help": "checkpointing mode for pipeline model parallelism"}, + ) + zero_sharding: ZERO_SHARDING_CHOICES = field( + default="none", metadata={"help": "ZeRO sharding"} + ) + fp16: bool = II("common.fp16") + memory_efficient_fp16: bool = II("common.memory_efficient_fp16") + tpu: bool = II("common.tpu") + # configuration for --ddp-backend=fully_sharded + no_reshard_after_forward: bool = field( + default=False, + metadata={"help": "don't reshard parameters after forward pass"}, + ) + fp32_reduce_scatter: bool = field( + default=False, + metadata={"help": "reduce-scatter grads in FP32"}, + ) + cpu_offload: bool = field( + default=False, metadata={"help": "offload FP32 params to CPU"} + ) + use_sharded_state: bool = field( + default=False, + metadata={"help": "use sharded checkpoint files"}, + ) + not_fsdp_flatten_parameters: bool = field( + default=False, + metadata={"help": "not flatten parameter param for fsdp"}, + ) + + +@dataclass +class DatasetConfig(FairseqDataclass): + num_workers: int = field( + default=1, metadata={"help": "how many subprocesses to use for data loading"} + ) + skip_invalid_size_inputs_valid_test: bool = field( + default=False, + metadata={"help": "ignore too long or too short lines in valid and test set"}, + ) + max_tokens: Optional[int] = field( + default=None, metadata={"help": "maximum number of tokens in a batch"} + ) + batch_size: Optional[int] = field( + default=None, + metadata={ + "help": "number of examples in a batch", + "argparse_alias": "--max-sentences", + }, + ) + required_batch_size_multiple: int = field( + default=8, metadata={"help": "batch size will be a multiplier of this value"} + ) + required_seq_len_multiple: int = field( + default=1, + metadata={ + "help": "maximum sequence length in batch will be a multiplier of this value" + }, + ) + dataset_impl: Optional[DATASET_IMPL_CHOICES] = field( + default=None, metadata={"help": "output dataset implementation"} + ) + data_buffer_size: int = field( + default=10, metadata={"help": "Number of batches to preload"} + ) + train_subset: str = field( + default="train", + metadata={"help": "data subset to use for training (e.g. train, valid, test)"}, + ) + valid_subset: str = field( + default="valid", + metadata={ + "help": "comma separated list of data subsets to use for validation" + " (e.g. train, valid, test)" + }, + ) + combine_valid_subsets: Optional[bool] = field( + default=None, + metadata={ + "help": "comma separated list of data subsets to use for validation" + " (e.g. train, valid, test)", + "argparse_alias": "--combine-val", + }, + ) + ignore_unused_valid_subsets: Optional[bool] = field( + default=False, + metadata={"help": "do not raise error if valid subsets are ignored"}, + ) + + validate_interval: int = field( + default=1, metadata={"help": "validate every N epochs"} + ) + validate_interval_updates: int = field( + default=0, metadata={"help": "validate every N updates"} + ) + validate_after_updates: int = field( + default=0, metadata={"help": "dont validate until reaching this many updates"} + ) + fixed_validation_seed: Optional[int] = field( + default=None, metadata={"help": "specified random seed for validation"} + ) + disable_validation: bool = field( + default=False, metadata={"help": "disable validation"} + ) + max_tokens_valid: Optional[int] = field( + default=II("dataset.max_tokens"), + metadata={ + "help": "maximum number of tokens in a validation batch" + " (defaults to --max-tokens)" + }, + ) + batch_size_valid: Optional[int] = field( + default=II("dataset.batch_size"), + metadata={ + "help": "batch size of the validation batch (defaults to --batch-size)", + "argparse_alias": "--max-sentences-valid", + }, + ) + max_valid_steps: Optional[int] = field( + default=None, + metadata={"help": "How many batches to evaluate", "argparse_alias": "--nval"}, + ) + curriculum: int = field( + default=0, metadata={"help": "don't shuffle batches for first N epochs"} + ) + gen_subset: str = field( + default="test", + metadata={"help": "data subset to generate (train, valid, test)"}, + ) + num_shards: int = field( + default=1, metadata={"help": "shard generation over N shards"} + ) + shard_id: int = field( + default=0, metadata={"help": "id of the shard to generate (id < num_shards)"} + ) + grouped_shuffling: bool = field( + default=False, + metadata={ + "help": "shuffle batches in groups of num_shards to enable similar sequence lengths on each GPU worker when batches are sorted by length", + }, + ) + update_epoch_batch_itr: bool = field( + default=II("dataset.grouped_shuffling"), + metadata={ + "help": "if true then prevents the reuse the epoch batch iterator by setting can_reuse_epoch_itr to false, defaults to --grouped-shuffling )", + }, + ) + update_ordered_indices_seed: bool = field( + default=False, + metadata={ + "help": "if true then increment seed with epoch for getting batch iterators, defautls to False.", + }, + ) + + +@dataclass +class OptimizationConfig(FairseqDataclass): + max_epoch: int = field( + default=0, metadata={"help": "force stop training at specified epoch"} + ) + max_update: int = field( + default=0, metadata={"help": "force stop training at specified update"} + ) + stop_time_hours: float = field( + default=0, + metadata={ + "help": "force stop training after specified cumulative time (if >0)" + }, + ) + clip_norm: float = field( + default=0.0, metadata={"help": "clip threshold of gradients"} + ) + sentence_avg: bool = field( + default=False, + metadata={ + "help": "normalize gradients by the number of sentences in a batch" + " (default is to normalize by number of tokens)" + }, + ) + update_freq: List[int] = field( + default_factory=lambda: [1], + metadata={"help": "update parameters every N_i batches, when in epoch i"}, + ) + lr: List[float] = field( + default_factory=lambda: [0.25], + metadata={ + "help": "learning rate for the first N epochs; all epochs >N using LR_N" + " (note: this may be interpreted differently depending on --lr-scheduler)" + }, + ) + stop_min_lr: float = field( + default=-1.0, + metadata={"help": "stop training when the learning rate reaches this minimum"}, + ) + use_bmuf: bool = field( + default=False, + metadata={ + "help": "specify global optimizer for syncing models on different GPUs/shards" + }, + ) + skip_remainder_batch: Optional[bool] = field( + default=False, + metadata={ + "help": "if set, include the last (partial) batch of each epoch in training" + " (default is to skip it)." + }, + ) + + +@dataclass +class CheckpointConfig(FairseqDataclass): + save_dir: str = field( + default="checkpoints", metadata={"help": "path to save checkpoints"} + ) + restore_file: str = field( + default="checkpoint_last.pt", + metadata={ + "help": "filename from which to load checkpoint " + "(default: /checkpoint_last.pt" + }, + ) + continue_once: Optional[str] = field( + default=None, + metadata={ + "help": "continues from this checkpoint, unless a checkpoint indicated in 'restore_file' option is present" + }, + ) + finetune_from_model: Optional[str] = field( + default=None, + metadata={ + "help": "finetune from a pretrained model; note that meters and lr scheduler will be reset" + }, + ) + reset_dataloader: bool = field( + default=False, + metadata={ + "help": "if set, does not reload dataloader state from the checkpoint" + }, + ) + reset_lr_scheduler: bool = field( + default=False, + metadata={ + "help": "if set, does not load lr scheduler state from the checkpoint" + }, + ) + reset_meters: bool = field( + default=False, + metadata={"help": "if set, does not load meters from the checkpoint"}, + ) + reset_optimizer: bool = field( + default=False, + metadata={"help": "if set, does not load optimizer state from the checkpoint"}, + ) + optimizer_overrides: str = field( + default="{}", + metadata={ + "help": "a dictionary used to override optimizer args when loading a checkpoint" + }, + ) + save_interval: int = field( + default=1, metadata={"help": "save a checkpoint every N epochs"} + ) + save_interval_updates: int = field( + default=0, metadata={"help": "save a checkpoint (and validate) every N updates"} + ) + keep_interval_updates: int = field( + default=-1, + metadata={ + "help": "keep the last N checkpoints saved with --save-interval-updates" + }, + ) + keep_interval_updates_pattern: int = field( + default=-1, + metadata={ + "help": "when used with --keep-interval-updates, skips deleting " + "any checkpoints with update X where " + "X %% keep_interval_updates_pattern == 0" + }, + ) + keep_last_epochs: int = field( + default=-1, metadata={"help": "keep last N epoch checkpoints"} + ) + keep_best_checkpoints: int = field( + default=-1, metadata={"help": "keep best N checkpoints based on scores"} + ) + no_save: bool = field( + default=False, metadata={"help": "don't save models or checkpoints"} + ) + no_epoch_checkpoints: bool = field( + default=False, metadata={"help": "only store last and best checkpoints"} + ) + no_last_checkpoints: bool = field( + default=False, metadata={"help": "don't store last checkpoints"} + ) + no_save_optimizer_state: bool = field( + default=False, + metadata={"help": "don't save optimizer-state as part of checkpoint"}, + ) + best_checkpoint_metric: str = field( + default="loss", metadata={"help": 'metric to use for saving "best" checkpoints'} + ) + maximize_best_checkpoint_metric: bool = field( + default=False, + metadata={ + "help": 'select the largest metric value for saving "best" checkpoints' + }, + ) + patience: int = field( + default=-1, + metadata={ + "help": ( + "early stop training if valid performance doesn't " + "improve for N consecutive validation runs; note " + "that this is influenced by --validate-interval" + ) + }, + ) + checkpoint_suffix: str = field( + default="", metadata={"help": "suffix to add to the checkpoint file name"} + ) + checkpoint_shard_count: int = field( + default=1, + metadata={ + "help": "Number of shards containing the checkpoint - " + "if the checkpoint is over 300GB, it is preferable " + "to split it into shards to prevent OOM on CPU while loading " + "the checkpoint" + }, + ) + load_checkpoint_on_all_dp_ranks: bool = field( + default=False, + metadata={ + "help": "load checkpoints on all data parallel devices " + "(default: only load on rank 0 and broadcast to other devices)" + }, + ) + write_checkpoints_asynchronously: bool = field( + default=False, + metadata={ + "help": ( + "Write checkpoints asynchronously in a separate " + "thread. NOTE: This feature is currently being tested." + ), + "argparse_alias": "--save-async", + }, + ) + model_parallel_size: int = II("common.model_parallel_size") + + +@dataclass +class FairseqBMUFConfig(FairseqDataclass): + block_lr: float = field( + default=1, metadata={"help": "block learning rate for bmuf"} + ) + block_momentum: float = field( + default=0.875, metadata={"help": "block momentum for bmuf"} + ) + global_sync_iter: int = field( + default=50, metadata={"help": "Iteration for syncing global model"} + ) + warmup_iterations: int = field( + default=500, metadata={"help": "warmup iterations for model to broadcast"} + ) + use_nbm: bool = field( + default=False, + metadata={"help": "Specify whether you want to use classical BM / Nesterov BM"}, + ) + average_sync: bool = field( + default=False, + metadata={ + "help": "Specify whether you want to average the local momentum after each sync" + }, + ) + distributed_world_size: int = II("distributed_training.distributed_world_size") + + +@dataclass +class GenerationConfig(FairseqDataclass): + beam: int = field( + default=5, + metadata={"help": "beam size"}, + ) + nbest: int = field( + default=1, + metadata={"help": "number of hypotheses to output"}, + ) + max_len_a: float = field( + default=0, + metadata={ + "help": "generate sequences of maximum length ax + b, where x is the source length" + }, + ) + max_len_b: int = field( + default=200, + metadata={ + "help": "generate sequences of maximum length ax + b, where x is the source length" + }, + ) + min_len: int = field( + default=1, + metadata={"help": "minimum generation length"}, + ) + match_source_len: bool = field( + default=False, + metadata={"help": "generations should match the source length"}, + ) + unnormalized: bool = field( + default=False, + metadata={"help": "compare unnormalized hypothesis scores"}, + ) + no_early_stop: bool = field( + default=False, + metadata={"help": "deprecated"}, + ) + no_beamable_mm: bool = field( + default=False, + metadata={"help": "don't use BeamableMM in attention layers"}, + ) + lenpen: float = field( + default=1, + metadata={ + "help": "length penalty: <1.0 favors shorter, >1.0 favors longer sentences" + }, + ) + unkpen: float = field( + default=0, + metadata={ + "help": "unknown word penalty: <0 produces more unks, >0 produces fewer" + }, + ) + replace_unk: Optional[str] = field( + default=None, + metadata={ + "help": "perform unknown replacement (optionally with alignment dictionary)", + "argparse_const": "@@ ", + }, + ) + sacrebleu: bool = field( + default=False, + metadata={"help": "score with sacrebleu"}, + ) + score_reference: bool = field( + default=False, + metadata={"help": "just score the reference translation"}, + ) + prefix_size: int = field( + default=0, + metadata={"help": "initialize generation by target prefix of given length"}, + ) + no_repeat_ngram_size: int = field( + default=0, + metadata={ + "help": "ngram blocking such that this size ngram cannot be repeated in the generation" + }, + ) + sampling: bool = field( + default=False, + metadata={"help": "sample hypotheses instead of using beam search"}, + ) + sampling_topk: int = field( + default=-1, + metadata={"help": "sample from top K likely next words instead of all words"}, + ) + sampling_topp: float = field( + default=-1.0, + metadata={ + "help": "sample from the smallest set whose cumulative probability mass exceeds p for next words" + }, + ) + constraints: Optional[GENERATION_CONSTRAINTS_CHOICES] = field( + default=None, + metadata={ + "help": "enables lexically constrained decoding", + "argparse_const": "ordered", + }, + ) + temperature: float = field( + default=1.0, + metadata={"help": "temperature for generation"}, + ) + diverse_beam_groups: int = field( + default=-1, + metadata={"help": "number of groups for Diverse Beam Search"}, + ) + diverse_beam_strength: float = field( + default=0.5, + metadata={"help": "strength of diversity penalty for Diverse Beam Search"}, + ) + diversity_rate: float = field( + default=-1.0, + metadata={"help": "strength of diversity penalty for Diverse Siblings Search"}, + ) + print_alignment: Optional[PRINT_ALIGNMENT_CHOICES] = field( + default=None, + metadata={ + "help": "if set, uses attention feedback to compute and print alignment to source tokens " + "(valid options are: hard, soft, otherwise treated as hard alignment)", + "argparse_const": "hard", + }, + ) + print_step: bool = field( + default=False, + metadata={"help": "print steps"}, + ) + lm_path: Optional[str] = field( + default=None, + metadata={"help": "path to lm checkpoint for lm fusion"}, + ) + lm_weight: float = field( + default=0.0, + metadata={"help": "weight for lm probs for lm fusion"}, + ) + + # arguments for iterative refinement generator + iter_decode_eos_penalty: float = field( + default=0.0, + metadata={"help": "if > 0.0, it penalized early-stopping in decoding."}, + ) + iter_decode_max_iter: int = field( + default=10, + metadata={"help": "maximum iterations for iterative refinement."}, + ) + iter_decode_force_max_iter: bool = field( + default=False, + metadata={ + "help": "if set, run exact the maximum number of iterations without early stop" + }, + ) + iter_decode_with_beam: int = field( + default=1, + metadata={ + "help": "if > 1, model will generate translations varying by the lengths." + }, + ) + iter_decode_with_external_reranker: bool = field( + default=False, + metadata={ + "help": "if set, the last checkpoint are assumed to be a reranker to rescore the translations" + }, + ) + retain_iter_history: bool = field( + default=False, + metadata={ + "help": "if set, decoding returns the whole history of iterative refinement" + }, + ) + retain_dropout: bool = field( + default=False, + metadata={"help": "Use dropout at inference time"}, + ) + # temporarily set to Any until https://github.com/facebookresearch/hydra/issues/1117 is fixed + # retain_dropout_modules: Optional[List[str]] = field( + retain_dropout_modules: Any = field( + default=None, + metadata={ + "help": "if set, only retain dropout for the specified modules; " + "if not set, then dropout will be retained for all modules" + }, + ) + # special decoding format for advanced decoding. + decoding_format: Optional[GENERATION_DECODING_FORMAT_CHOICES] = field( + default=None, + metadata={"help": "special decoding format for advanced decoding."}, + ) + no_seed_provided: bool = field( + default=False, + metadata={"help": "if set, dont use seed for initializing random generators"}, + ) + eos_token: Optional[str] = field( + default=None, + metadata={"help": "EOS token"}, + ) + + +@dataclass +class CommonEvalConfig(FairseqDataclass): + path: Optional[str] = field( + default=None, + metadata={"help": "path(s) to model file(s), colon separated"}, + ) + post_process: Optional[str] = field( + default=None, + metadata={ + "help": ( + "post-process text by removing BPE, letter segmentation, etc. " + "Valid options can be found in fairseq.data.utils.post_process." + ), + "argparse_const": "subword_nmt", + "argparse_alias": "--remove-bpe", + }, + ) + quiet: bool = field(default=False, metadata={"help": "only print final scores"}) + model_overrides: str = field( + default="{}", + metadata={ + "help": "a dictionary used to override model args at generation that were used during model training" + }, + ) + results_path: Optional[str] = field( + default=None, metadata={"help": "path to save eval results (optional)"} + ) + + +@dataclass +class EvalLMConfig(FairseqDataclass): + output_word_probs: bool = field( + default=False, + metadata={ + "help": "if set, outputs words and their predicted log probabilities to standard output" + }, + ) + output_word_stats: bool = field( + default=False, + metadata={ + "help": "if set, outputs word statistics such as word count, average probability, etc" + }, + ) + context_window: int = field( + default=0, + metadata={ + "help": "ensures that every evaluated token has access to a context of at least this size, if possible" + }, + ) + softmax_batch: int = field( + default=sys.maxsize, + metadata={ + "help": "if BxT is more than this, will batch the softmax over vocab to this amount of tokens, in order to fit into GPU memory" + }, + ) + + +@dataclass +class InteractiveConfig(FairseqDataclass): + buffer_size: int = field( + default=0, + metadata={ + "help": "read this many sentences into a buffer before processing them" + }, + ) + input: str = field( + default="-", + metadata={"help": "file to read from; use - for stdin"}, + ) + + +@dataclass +class EMAConfig(FairseqDataclass): + store_ema: bool = field( + default=False, metadata={help: "store exponential moving average shadow model"} + ) + ema_decay: float = field( + default=0.9999, metadata={"help": "decay for exponential moving average model"} + ) + ema_start_update: int = field( + default=0, metadata={"help": "start EMA update after this many model updates"} + ) + ema_seed_model: Optional[str] = field( + default=None, + metadata={ + "help": "Seed to load EMA model from. " + "Used to load EMA model separately from the actual model." + }, + ) + ema_update_freq: int = field( + default=1, metadata={"help": "Do EMA update every this many model updates"} + ) + ema_fp32: bool = field( + default=False, + metadata={"help": "If true, store EMA model in fp32 even if model is in fp16"}, + ) + + +@dataclass +class FairseqConfig(FairseqDataclass): + common: CommonConfig = CommonConfig() + common_eval: CommonEvalConfig = CommonEvalConfig() + distributed_training: DistributedTrainingConfig = DistributedTrainingConfig() + dataset: DatasetConfig = DatasetConfig() + optimization: OptimizationConfig = OptimizationConfig() + checkpoint: CheckpointConfig = CheckpointConfig() + bmuf: FairseqBMUFConfig = FairseqBMUFConfig() + generation: GenerationConfig = GenerationConfig() + eval_lm: EvalLMConfig = EvalLMConfig() + interactive: InteractiveConfig = InteractiveConfig() + model: Any = MISSING + task: Any = None + criterion: Any = None + optimizer: Any = None + lr_scheduler: Any = None + scoring: Any = None + bpe: Any = None + tokenizer: Any = None + ema: EMAConfig = EMAConfig() diff --git a/PyTorch/NLP/new-Transformer/fairseq/dataclass/constants.py b/PyTorch/NLP/new-Transformer/fairseq/dataclass/constants.py new file mode 100644 index 00000000..5af92f2b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/dataclass/constants.py @@ -0,0 +1,56 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from enum import Enum, EnumMeta +from typing import List + + +class StrEnumMeta(EnumMeta): + # this is workaround for submitit pickling leading to instance checks failing in hydra for StrEnum, see + # https://github.com/facebookresearch/hydra/issues/1156 + @classmethod + def __instancecheck__(cls, other): + return "enum" in str(type(other)) + + +class StrEnum(Enum, metaclass=StrEnumMeta): + def __str__(self): + return self.value + + def __eq__(self, other: str): + return self.value == other + + def __repr__(self): + return self.value + + def __hash__(self): + return hash(str(self)) + + +def ChoiceEnum(choices: List[str]): + """return the Enum class used to enforce list of choices""" + return StrEnum("Choices", {k: k for k in choices}) + + +LOG_FORMAT_CHOICES = ChoiceEnum(["json", "none", "simple", "tqdm"]) +DDP_BACKEND_CHOICES = ChoiceEnum( + [ + "c10d", # alias for pytorch_ddp + "fully_sharded", # FullyShardedDataParallel from fairscale + "legacy_ddp", + "no_c10d", # alias for legacy_ddp + "pytorch_ddp", + "slowmo", + ] +) +DDP_COMM_HOOK_CHOICES = ChoiceEnum(["none", "fp16"]) +DATASET_IMPL_CHOICES = ChoiceEnum(["raw", "lazy", "cached", "mmap", "fasta", "huffman"]) +GENERATION_CONSTRAINTS_CHOICES = ChoiceEnum(["ordered", "unordered"]) +GENERATION_DECODING_FORMAT_CHOICES = ChoiceEnum( + ["unigram", "ensemble", "vote", "dp", "bs"] +) +ZERO_SHARDING_CHOICES = ChoiceEnum(["none", "os"]) +PIPELINE_CHECKPOINT_CHOICES = ChoiceEnum(["always", "never", "except_last"]) +PRINT_ALIGNMENT_CHOICES = ChoiceEnum(["hard", "soft"]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/dataclass/initialize.py b/PyTorch/NLP/new-Transformer/fairseq/dataclass/initialize.py new file mode 100644 index 00000000..5a7784ba --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/dataclass/initialize.py @@ -0,0 +1,61 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +import logging +from hydra.core.config_store import ConfigStore +from fairseq.dataclass.configs import FairseqConfig +from omegaconf import DictConfig, OmegaConf + + +logger = logging.getLogger(__name__) + + +def hydra_init(cfg_name="config") -> None: + + cs = ConfigStore.instance() + cs.store(name=f"{cfg_name}", node=FairseqConfig) + + for k in FairseqConfig.__dataclass_fields__: + v = FairseqConfig.__dataclass_fields__[k].default + try: + cs.store(name=k, node=v) + except BaseException: + logger.error(f"{k} - {v}") + raise + + +def add_defaults(cfg: DictConfig) -> None: + """This function adds default values that are stored in dataclasses that hydra doesn't know about""" + + from fairseq.registry import REGISTRIES + from fairseq.tasks import TASK_DATACLASS_REGISTRY + from fairseq.models import ARCH_MODEL_NAME_REGISTRY, MODEL_DATACLASS_REGISTRY + from fairseq.dataclass.utils import merge_with_parent + from typing import Any + + OmegaConf.set_struct(cfg, False) + + for k, v in FairseqConfig.__dataclass_fields__.items(): + field_cfg = cfg.get(k) + if field_cfg is not None and v.type == Any: + dc = None + + if isinstance(field_cfg, str): + field_cfg = DictConfig({"_name": field_cfg}) + field_cfg.__dict__["_parent"] = field_cfg.__dict__["_parent"] + + name = getattr(field_cfg, "_name", None) + + if k == "task": + dc = TASK_DATACLASS_REGISTRY.get(name) + elif k == "model": + name = ARCH_MODEL_NAME_REGISTRY.get(name, name) + dc = MODEL_DATACLASS_REGISTRY.get(name) + elif k in REGISTRIES: + dc = REGISTRIES[k]["dataclass_registry"].get(name) + + if dc is not None: + cfg[k] = merge_with_parent(dc, field_cfg) diff --git a/PyTorch/NLP/new-Transformer/fairseq/dataclass/utils.py b/PyTorch/NLP/new-Transformer/fairseq/dataclass/utils.py new file mode 100644 index 00000000..f307fe6e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/dataclass/utils.py @@ -0,0 +1,493 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import ast +import inspect +import logging +import os +import re +from argparse import ArgumentError, ArgumentParser, Namespace +from dataclasses import _MISSING_TYPE, MISSING, is_dataclass +from enum import Enum +from typing import Any, Dict, List, Optional, Tuple, Type + +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.configs import FairseqConfig +from hydra.core.global_hydra import GlobalHydra +from hydra.experimental import compose, initialize +from omegaconf import DictConfig, OmegaConf, open_dict, _utils + +logger = logging.getLogger(__name__) + + +def eval_str_list(x, x_type=float): + if x is None: + return None + if isinstance(x, str): + if len(x) == 0: + return [] + x = ast.literal_eval(x) + try: + return list(map(x_type, x)) + except TypeError: + return [x_type(x)] + + +def interpret_dc_type(field_type): + if isinstance(field_type, str): + raise RuntimeError("field should be a type") + + if field_type == Any: + return str + + typestring = str(field_type) + if re.match( + r"(typing.|^)Union\[(.*), NoneType\]$", typestring + ) or typestring.startswith("typing.Optional"): + return field_type.__args__[0] + return field_type + + +def gen_parser_from_dataclass( + parser: ArgumentParser, + dataclass_instance: FairseqDataclass, + delete_default: bool = False, + with_prefix: Optional[str] = None, +) -> None: + """ + convert a dataclass instance to tailing parser arguments. + + If `with_prefix` is provided, prefix all the keys in the resulting parser with it. It means that we are + building a flat namespace from a structured dataclass (see transformer_config.py for example). + """ + + def argparse_name(name: str): + if name == "data" and (with_prefix is None or with_prefix == ""): + # normally data is positional args, so we don't add the -- nor the prefix + return name + if name == "_name": + # private member, skip + return None + full_name = "--" + name.replace("_", "-") + if with_prefix is not None and with_prefix != "": + # if a prefix is specified, construct the prefixed arg name + full_name = with_prefix + "-" + full_name[2:] # strip -- when composing + return full_name + + def get_kwargs_from_dc( + dataclass_instance: FairseqDataclass, k: str + ) -> Dict[str, Any]: + """k: dataclass attributes""" + + kwargs = {} + + field_type = dataclass_instance._get_type(k) + inter_type = interpret_dc_type(field_type) + + field_default = dataclass_instance._get_default(k) + + if isinstance(inter_type, type) and issubclass(inter_type, Enum): + field_choices = [t.value for t in list(inter_type)] + else: + field_choices = None + + field_help = dataclass_instance._get_help(k) + field_const = dataclass_instance._get_argparse_const(k) + + if isinstance(field_default, str) and field_default.startswith("${"): + kwargs["default"] = field_default + else: + if field_default is MISSING: + kwargs["required"] = True + if field_choices is not None: + kwargs["choices"] = field_choices + if ( + isinstance(inter_type, type) + and (issubclass(inter_type, List) or issubclass(inter_type, Tuple)) + ) or ("List" in str(inter_type) or "Tuple" in str(inter_type)): + if "int" in str(inter_type): + kwargs["type"] = lambda x: eval_str_list(x, int) + elif "float" in str(inter_type): + kwargs["type"] = lambda x: eval_str_list(x, float) + elif "str" in str(inter_type): + kwargs["type"] = lambda x: eval_str_list(x, str) + else: + raise NotImplementedError( + "parsing of type " + str(inter_type) + " is not implemented" + ) + if field_default is not MISSING: + kwargs["default"] = ( + ",".join(map(str, field_default)) + if field_default is not None + else None + ) + elif ( + isinstance(inter_type, type) and issubclass(inter_type, Enum) + ) or "Enum" in str(inter_type): + kwargs["type"] = str + if field_default is not MISSING: + if isinstance(field_default, Enum): + kwargs["default"] = field_default.value + else: + kwargs["default"] = field_default + elif inter_type is bool: + kwargs["action"] = ( + "store_false" if field_default is True else "store_true" + ) + kwargs["default"] = field_default + else: + kwargs["type"] = inter_type + if field_default is not MISSING: + kwargs["default"] = field_default + + # build the help with the hierarchical prefix + if with_prefix is not None and with_prefix != "" and field_help is not None: + field_help = with_prefix[2:] + ": " + field_help + + kwargs["help"] = field_help + if field_const is not None: + kwargs["const"] = field_const + kwargs["nargs"] = "?" + + return kwargs + + for k in dataclass_instance._get_all_attributes(): + field_name = argparse_name(dataclass_instance._get_name(k)) + field_type = dataclass_instance._get_type(k) + if field_name is None: + continue + elif inspect.isclass(field_type) and issubclass(field_type, FairseqDataclass): + # for fields that are of type FairseqDataclass, we can recursively + # add their fields to the namespace (so we add the args from model, task, etc. to the root namespace) + prefix = None + if with_prefix is not None: + # if a prefix is specified, then we don't want to copy the subfields directly to the root namespace + # but we prefix them with the name of the current field. + prefix = field_name + gen_parser_from_dataclass(parser, field_type(), delete_default, prefix) + continue + + kwargs = get_kwargs_from_dc(dataclass_instance, k) + + field_args = [field_name] + alias = dataclass_instance._get_argparse_alias(k) + if alias is not None: + field_args.append(alias) + + if "default" in kwargs: + if isinstance(kwargs["default"], str) and kwargs["default"].startswith( + "${" + ): + if kwargs["help"] is None: + # this is a field with a name that will be added elsewhere + continue + else: + del kwargs["default"] + if delete_default and "default" in kwargs: + del kwargs["default"] + try: + parser.add_argument(*field_args, **kwargs) + except ArgumentError: + pass + + +def _set_legacy_defaults(args, cls): + """Helper to set default arguments based on *add_args*.""" + if not hasattr(cls, "add_args"): + return + + import argparse + + parser = argparse.ArgumentParser( + argument_default=argparse.SUPPRESS, allow_abbrev=False + ) + cls.add_args(parser) + # copied from argparse.py: + defaults = argparse.Namespace() + for action in parser._actions: + if action.dest is not argparse.SUPPRESS: + if not hasattr(defaults, action.dest): + if action.default is not argparse.SUPPRESS: + setattr(defaults, action.dest, action.default) + for key, default_value in vars(defaults).items(): + if not hasattr(args, key): + setattr(args, key, default_value) + + +def _override_attr( + sub_node: str, data_class: Type[FairseqDataclass], args: Namespace +) -> List[str]: + overrides = [] + + if not inspect.isclass(data_class) or not issubclass(data_class, FairseqDataclass): + return overrides + + def get_default(f): + if not isinstance(f.default_factory, _MISSING_TYPE): + return f.default_factory() + return f.default + + for k, v in data_class.__dataclass_fields__.items(): + if k.startswith("_"): + # private member, skip + continue + + val = get_default(v) if not hasattr(args, k) else getattr(args, k) + + field_type = interpret_dc_type(v.type) + if ( + isinstance(val, str) + and not val.startswith("${") # not interpolation + and field_type != str + and ( + not inspect.isclass(field_type) or not issubclass(field_type, Enum) + ) # not choices enum + ): + # upgrade old models that stored complex parameters as string + val = ast.literal_eval(val) + + if isinstance(val, tuple): + val = list(val) + + v_type = getattr(v.type, "__origin__", None) + if ( + (v_type is List or v_type is list or v_type is Optional) + # skip interpolation + and not (isinstance(val, str) and val.startswith("${")) + ): + # if type is int but val is float, then we will crash later - try to convert here + if hasattr(v.type, "__args__"): + t_args = v.type.__args__ + if len(t_args) == 1 and (t_args[0] is float or t_args[0] is int): + val = list(map(t_args[0], val)) + elif val is not None and ( + field_type is int or field_type is bool or field_type is float + ): + try: + val = field_type(val) + except: + pass # ignore errors here, they are often from interpolation args + + if val is None: + overrides.append("{}.{}=null".format(sub_node, k)) + elif val == "": + overrides.append("{}.{}=''".format(sub_node, k)) + elif isinstance(val, str): + val = val.replace("'", r"\'") + overrides.append("{}.{}='{}'".format(sub_node, k, val)) + elif isinstance(val, FairseqDataclass): + overrides += _override_attr(f"{sub_node}.{k}", type(val), args) + elif isinstance(val, Namespace): + sub_overrides, _ = override_module_args(val) + for so in sub_overrides: + overrides.append(f"{sub_node}.{k}.{so}") + else: + overrides.append("{}.{}={}".format(sub_node, k, val)) + + return overrides + + +def migrate_registry( + name, value, registry, args, overrides, deletes, use_name_as_val=False +): + if value in registry: + overrides.append("{}={}".format(name, value)) + overrides.append("{}._name={}".format(name, value)) + overrides.extend(_override_attr(name, registry[value], args)) + elif use_name_as_val and value is not None: + overrides.append("{}={}".format(name, value)) + else: + deletes.append(name) + + +def override_module_args(args: Namespace) -> Tuple[List[str], List[str]]: + """use the field in args to overrides those in cfg""" + overrides = [] + deletes = [] + + for k in FairseqConfig.__dataclass_fields__.keys(): + overrides.extend( + _override_attr(k, FairseqConfig.__dataclass_fields__[k].type, args) + ) + + if args is not None: + if hasattr(args, "task"): + from fairseq.tasks import TASK_DATACLASS_REGISTRY + + migrate_registry( + "task", args.task, TASK_DATACLASS_REGISTRY, args, overrides, deletes + ) + else: + deletes.append("task") + + # these options will be set to "None" if they have not yet been migrated + # so we can populate them with the entire flat args + CORE_REGISTRIES = {"criterion", "optimizer", "lr_scheduler"} + + from fairseq.registry import REGISTRIES + + for k, v in REGISTRIES.items(): + if hasattr(args, k): + migrate_registry( + k, + getattr(args, k), + v["dataclass_registry"], + args, + overrides, + deletes, + use_name_as_val=k not in CORE_REGISTRIES, + ) + else: + deletes.append(k) + + no_dc = True + if hasattr(args, "arch"): + from fairseq.models import ARCH_MODEL_REGISTRY, ARCH_MODEL_NAME_REGISTRY + + if args.arch in ARCH_MODEL_REGISTRY: + m_cls = ARCH_MODEL_REGISTRY[args.arch] + dc = getattr(m_cls, "__dataclass", None) + if dc is not None: + m_name = ARCH_MODEL_NAME_REGISTRY[args.arch] + overrides.append("model={}".format(m_name)) + overrides.append("model._name={}".format(args.arch)) + # override model params with those exist in args + overrides.extend(_override_attr("model", dc, args)) + no_dc = False + if no_dc: + deletes.append("model") + + return overrides, deletes + + +class omegaconf_no_object_check: + def __init__(self): + self.old_is_primitive = _utils.is_primitive_type + + def __enter__(self): + _utils.is_primitive_type = lambda _: True + + def __exit__(self, type, value, traceback): + _utils.is_primitive_type = self.old_is_primitive + + +def convert_namespace_to_omegaconf(args: Namespace) -> DictConfig: + """Convert a flat argparse.Namespace to a structured DictConfig.""" + + # Here we are using field values provided in args to override counterparts inside config object + overrides, deletes = override_module_args(args) + + # configs will be in fairseq/config after installation + config_path = os.path.join("..", "config") + + GlobalHydra.instance().clear() + + with initialize(config_path=config_path): + try: + composed_cfg = compose("config", overrides=overrides, strict=False) + except: + logger.error("Error when composing. Overrides: " + str(overrides)) + raise + + for k in deletes: + composed_cfg[k] = None + + cfg = OmegaConf.create( + OmegaConf.to_container(composed_cfg, resolve=True, enum_to_str=True) + ) + + # hack to be able to set Namespace in dict config. this should be removed when we update to newer + # omegaconf version that supports object flags, or when we migrate all existing models + from omegaconf import _utils + + with omegaconf_no_object_check(): + if cfg.task is None and getattr(args, "task", None): + cfg.task = Namespace(**vars(args)) + from fairseq.tasks import TASK_REGISTRY + + _set_legacy_defaults(cfg.task, TASK_REGISTRY[args.task]) + cfg.task._name = args.task + if cfg.model is None and getattr(args, "arch", None): + cfg.model = Namespace(**vars(args)) + from fairseq.models import ARCH_MODEL_REGISTRY + + _set_legacy_defaults(cfg.model, ARCH_MODEL_REGISTRY[args.arch]) + cfg.model._name = args.arch + if cfg.optimizer is None and getattr(args, "optimizer", None): + cfg.optimizer = Namespace(**vars(args)) + from fairseq.optim import OPTIMIZER_REGISTRY + + _set_legacy_defaults(cfg.optimizer, OPTIMIZER_REGISTRY[args.optimizer]) + cfg.optimizer._name = args.optimizer + if cfg.lr_scheduler is None and getattr(args, "lr_scheduler", None): + cfg.lr_scheduler = Namespace(**vars(args)) + from fairseq.optim.lr_scheduler import LR_SCHEDULER_REGISTRY + + _set_legacy_defaults( + cfg.lr_scheduler, LR_SCHEDULER_REGISTRY[args.lr_scheduler] + ) + cfg.lr_scheduler._name = args.lr_scheduler + if cfg.criterion is None and getattr(args, "criterion", None): + cfg.criterion = Namespace(**vars(args)) + from fairseq.criterions import CRITERION_REGISTRY + + _set_legacy_defaults(cfg.criterion, CRITERION_REGISTRY[args.criterion]) + cfg.criterion._name = args.criterion + + OmegaConf.set_struct(cfg, True) + return cfg + + +def overwrite_args_by_name(cfg: DictConfig, overrides: Dict[str, any]): + # this will be deprecated when we get rid of argparse and model_overrides logic + + from fairseq.registry import REGISTRIES + + with open_dict(cfg): + for k in cfg.keys(): + # "k in cfg" will return false if its a "mandatory value (e.g. ???)" + if k in cfg and isinstance(cfg[k], DictConfig): + if k in overrides and isinstance(overrides[k], dict): + for ok, ov in overrides[k].items(): + if isinstance(ov, dict) and cfg[k][ok] is not None: + overwrite_args_by_name(cfg[k][ok], ov) + else: + cfg[k][ok] = ov + else: + overwrite_args_by_name(cfg[k], overrides) + elif k in cfg and isinstance(cfg[k], Namespace): + for override_key, val in overrides.items(): + setattr(cfg[k], override_key, val) + elif k in overrides: + if ( + k in REGISTRIES + and overrides[k] in REGISTRIES[k]["dataclass_registry"] + ): + cfg[k] = DictConfig( + REGISTRIES[k]["dataclass_registry"][overrides[k]] + ) + overwrite_args_by_name(cfg[k], overrides) + cfg[k]._name = overrides[k] + else: + cfg[k] = overrides[k] + + +def merge_with_parent(dc: FairseqDataclass, cfg: DictConfig, remove_missing=False): + if remove_missing: + + if is_dataclass(dc): + target_keys = set(dc.__dataclass_fields__.keys()) + else: + target_keys = set(dc.keys()) + + with open_dict(cfg): + for k in list(cfg.keys()): + if k not in target_keys: + del cfg[k] + + merged_cfg = OmegaConf.merge(dc, cfg) + merged_cfg.__dict__["_parent"] = cfg.__dict__["_parent"] + OmegaConf.set_struct(merged_cfg, True) + return merged_cfg diff --git a/PyTorch/NLP/new-Transformer/fairseq/distributed/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/distributed/__init__.py new file mode 100644 index 00000000..9130db8f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/distributed/__init__.py @@ -0,0 +1,25 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .distributed_timeout_wrapper import DistributedTimeoutWrapper +from .fully_sharded_data_parallel import ( + fsdp_enable_wrap, + fsdp_wrap, + FullyShardedDataParallel, +) +from .legacy_distributed_data_parallel import LegacyDistributedDataParallel +from .module_proxy_wrapper import ModuleProxyWrapper +from .tpu_distributed_data_parallel import TPUDistributedDataParallel + + +__all__ = [ + "DistributedTimeoutWrapper", + "fsdp_enable_wrap", + "fsdp_wrap", + "FullyShardedDataParallel", + "LegacyDistributedDataParallel", + "ModuleProxyWrapper", + "TPUDistributedDataParallel", +] diff --git a/PyTorch/NLP/new-Transformer/fairseq/distributed/distributed_timeout_wrapper.py b/PyTorch/NLP/new-Transformer/fairseq/distributed/distributed_timeout_wrapper.py new file mode 100644 index 00000000..6e06b4b6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/distributed/distributed_timeout_wrapper.py @@ -0,0 +1,97 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +import signal +import threading + +from torch import nn + + +logger = logging.getLogger(__name__) + + +class DistributedTimeoutWrapper(nn.Module): + """ + A wrapper that kills the process if no progress is made within a given + *timeout*. The timer is reset every time :func:`forward` is called. + + Usage:: + + module = DistributedTimeoutWrapper(module, timeout=30) + x = module(input) + time.sleep(20) # safe + x = module(input) + time.sleep(45) # job will be killed before this returns + + Args: + module (nn.Module): module to wrap + timeout (int): number of seconds before killing the process + (set to a value <= 0 to disable the timeout) + signal (Optional): signal to send once timeout is triggered + """ + + def __init__(self, module: nn.Module, timeout: int, signal=signal.SIGINT): + super().__init__() + self.module = module + self.timeout = timeout + self.signal = signal + + if timeout > 0: + self._heartbeat = threading.Event() + self._heartbeat_thread = threading.Thread( + target=self._check_heartbeat, + args=(os.getpid(),), + daemon=True, + ) + self._heartbeat_thread.start() + self._terminated = False + else: + self._heartbeat = None + self._heartbeat_thread = None + + def __del__(self): + self.stop_timeout() + + def __getattr__(self, name): + """Forward missing attributes to wrapped module.""" + try: + return super().__getattr__(name) # defer to nn.Module's logic + except AttributeError: + return getattr(self.module, name) + + def stop_timeout(self): + if self._heartbeat_thread is not None: + self._terminated = True + self._heartbeat_thread.join() + + def state_dict(self, *args, **kwargs): + return self.module.state_dict(*args, **kwargs) + + def load_state_dict(self, *args, **kwargs): + return self.module.load_state_dict(*args, **kwargs) + + def forward(self, *args, **kwargs): + if self._heartbeat is not None: + self._heartbeat.set() + return self.module(*args, **kwargs) + + def _check_heartbeat(self, parent_pid): + self._heartbeat.wait() # wait for the first forward pass + while True: + self._heartbeat.clear() + success = self._heartbeat.wait(timeout=self.timeout) + if self._terminated: + break + elif not success: + logger.error( + ( + "Killing job for not making progress in {} seconds. " + "Set --heartbeat-timeout=-1 to disable this timeout." + ).format(int(self.timeout)) + ) + os.kill(parent_pid, self.signal) + return diff --git a/PyTorch/NLP/new-Transformer/fairseq/distributed/fully_sharded_data_parallel.py b/PyTorch/NLP/new-Transformer/fairseq/distributed/fully_sharded_data_parallel.py new file mode 100644 index 00000000..88dc698b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/distributed/fully_sharded_data_parallel.py @@ -0,0 +1,135 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import contextlib +from typing import Optional + +import torch +from fairseq.dataclass.configs import DistributedTrainingConfig +from fairseq.distributed import utils as dist_utils + + +try: + from fairscale.nn.data_parallel import FullyShardedDataParallel as FSDP + + has_FSDP = True +except ImportError: + FSDP = torch.nn.Module + has_FSDP = False + + +class FullyShardedDataParallel(FSDP): + """ + A small wrapper around fairscale's FullyShardedDataParallel (FSDP) with some + fairseq-specific checkpoint saving/loading logic. + + Args: + use_sharded_state (bool): if True, then ``state_dict`` will return + ``FSDP.local_state_dict`` and ``load_state_dict`` will call + ``FSDP.load_local_state_dict``. Otherwise, ``state_dict`` will + return the full model weights on data parallel rank 0 (empty on + other ranks) and ``load_state_dict`` will broadcast model weights + from rank 0 to other ranks. + """ + + def __init__(self, *args, use_sharded_state: bool = False, **kwargs): + if not has_FSDP: + raise ImportError( + "Cannot find FullyShardedDataParallel. " + "Please install fairscale with: pip install fairscale" + ) + super().__init__(*args, **kwargs) + self.use_sharded_state = use_sharded_state + + @property + def unwrapped_module(self) -> torch.nn.Module: + if self.flatten_parameters: + return self.module.module + else: + return self.module + + def state_dict(self, destination=None, prefix="", keep_vars=False): + if self.use_sharded_state: + return super().local_state_dict( + destination=destination, prefix=prefix, keep_vars=keep_vars + ) + else: + if self.rank == 0: + return super().state_dict( + destination=destination, prefix=prefix, keep_vars=keep_vars + ) + else: + # We must call state_dict() due to use of communication + # primitives. But we don't use the result. + super().state_dict() + return destination or {} + + def load_state_dict(self, state_dict, strict=True, model_cfg=None): + if self.use_sharded_state: + return super().load_local_state_dict(state_dict, strict=strict) + else: + state_dict = dist_utils.broadcast_object( + state_dict, src_rank=0, group=self.process_group + ) + return super().load_state_dict(state_dict, strict=strict) + + +@contextlib.contextmanager +def fsdp_enable_wrap(cfg: DistributedTrainingConfig): + try: + from fairscale.nn import enable_wrap + except ImportError: + raise ImportError( + "Cannot find FullyShardedDataParallel. " + "Please install fairscale with: pip install fairscale" + ) + if cfg.memory_efficient_fp16: + assert cfg.fp16 # memory_efficient_fp16 should imply fp16 + group = dist_utils.get_data_parallel_group() + if group is None and cfg.distributed_world_size == 1: + from fairscale.utils.testing import DummyProcessGroup + + group = DummyProcessGroup(rank=0, size=1) + fsdp_config = { + "process_group": group, + "reshard_after_forward": not cfg.no_reshard_after_forward, + "mixed_precision": cfg.fp16 and not cfg.memory_efficient_fp16, + "fp32_reduce_scatter": cfg.fp32_reduce_scatter, + "flatten_parameters": not cfg.not_fsdp_flatten_parameters, + "cpu_offload": cfg.cpu_offload, + "compute_dtype": torch.float16 if cfg.fp16 else torch.float32, + "bucket_cap_mb": cfg.bucket_cap_mb, + "state_dict_device": torch.device("cpu"), # reduce GPU mem usage + } + with enable_wrap( + wrapper_cls=FullyShardedDataParallel, + use_sharded_state=cfg.use_sharded_state, + **fsdp_config, + ): + yield + + +def fsdp_wrap(module, min_num_params: Optional[int] = None, **kwargs): + """ + Helper to wrap layers/modules in FSDP. This falls back to a no-op if + fairscale is not available. + + Args: + module (nn.Module): module to (maybe) wrap + min_num_params (int, Optional): minimum number of layer params to wrap + """ + try: + from fairscale.nn import wrap + + if min_num_params is not None: + num_params = sum(p.numel() for p in module.parameters()) + if num_params >= min_num_params: + return wrap(module, **kwargs) + else: + return module + else: + return wrap(module, **kwargs) + except ImportError: + return module diff --git a/PyTorch/NLP/new-Transformer/fairseq/distributed/legacy_distributed_data_parallel.py b/PyTorch/NLP/new-Transformer/fairseq/distributed/legacy_distributed_data_parallel.py new file mode 100644 index 00000000..cd434c73 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/distributed/legacy_distributed_data_parallel.py @@ -0,0 +1,165 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +""" +A modified version of the legacy DistributedDataParallel module that uses c10d +communication primitives. This version is simpler than the latest PyTorch +version and is useful for debugging. Notably it does not overlap gradient +communication with the backward pass, which makes it slower but more robust +than the PyTorch version. + +This version also supports the *no_sync* context manager, which allows faster +training with `--update-freq`. +""" + +from collections import OrderedDict +from contextlib import contextmanager + +import torch +from torch import nn + +from fairseq.distributed import utils + + +class LegacyDistributedDataParallel(nn.Module): + """Implements distributed data parallelism at the module level. + + A simplified version of :class:`torch.nn.parallel.DistributedDataParallel`. + This version uses a c10d process group for communication and does not + broadcast buffers. + + Args: + module (~torch.nn.Module): module to be parallelized + process_group: the c10d process group to be used for distributed data + parallel all-reduction. + buffer_size (int, optional): number of elements to buffer before + performing all-reduce (default: 256M). + """ + + def __init__(self, module, process_group, buffer_size=2**28): + super().__init__() + + self.module = module + self.process_group = process_group + self.world_size = utils.get_world_size(self.process_group) + + # Never use a bigger buffer than the number of model params + self.buffer_size = min(buffer_size, sum(p.numel() for p in module.parameters())) + self.buffer = None + + # We can also forcibly accumulate grads locally and only do the + # all-reduce at some later time + self.accumulate_grads = False + + # make per-device lists of parameters + paramlists = OrderedDict() + for param in self.module.parameters(): + device = param.device + if paramlists.get(device) is None: + paramlists[device] = [] + paramlists[device] += [param] + self.per_device_params = list(paramlists.values()) + + @contextmanager + def no_sync(self): + """A context manager to disable gradient synchronization.""" + old_accumulate_grads = self.accumulate_grads + self.accumulate_grads = True + yield + self.accumulate_grads = old_accumulate_grads + + def forward(self, *inputs, **kwargs): + return self.module(*inputs, **kwargs) + + def all_reduce_grads(self): + """ + This function must be called explicitly after backward to reduce + gradients. There is no automatic hook like c10d. + """ + + def all_reduce_params(params): + buffer = self.buffer + nonzero_buffer = False + if len(params) > 1: + offset = 0 + for p in params: + sz = p.numel() + if p.grad is not None: + buffer[offset : offset + sz].copy_(p.grad.data.view(-1)) + nonzero_buffer = True + else: + buffer[offset : offset + sz].zero_() + offset += sz + else: + # we only have a single grad to all-reduce + p = params[0] + if p.grad is not None: + buffer = p.grad.data + nonzero_buffer = True + elif p.numel() <= self.buffer.numel(): + buffer = buffer[: p.numel()] + buffer.zero_() + else: + buffer = torch.zeros_like(p) + + if nonzero_buffer: + buffer.div_(self.world_size) + + utils.all_reduce(buffer, self.process_group) + + # copy all-reduced grads back into their original place + offset = 0 + for p in params: + sz = p.numel() + if p.grad is not None: + p.grad.data.copy_(buffer[offset : offset + sz].view_as(p)) + else: + p.grad = buffer[offset : offset + sz].view_as(p).clone() + offset += sz + + def reduction_fn(): + # This function only needs to be called once + if self.accumulate_grads: + return + + if self.buffer is None: + self.buffer = next(self.module.parameters()).new(self.buffer_size) + + for params in self.per_device_params: + # All-reduce the gradients in buckets + offset = 0 + buffered_params = [] + for param in params: + if not param.requires_grad: + continue + if param.grad is None: + param.grad = torch.zeros_like(param) + + if hasattr(param, "expert"): + # Skip gradient sync for unshared parameters + continue + + if param.grad.requires_grad: + raise RuntimeError( + "DistributedDataParallel only works " + "with gradients that don't require " + "grad" + ) + sz = param.numel() + if sz > self.buffer.numel(): + # all-reduce big params directly + all_reduce_params([param]) + else: + if offset + sz > self.buffer.numel(): + all_reduce_params(buffered_params) + offset = 0 + buffered_params.clear() + buffered_params.append(param) + offset += sz + + if len(buffered_params) > 0: + all_reduce_params(buffered_params) + + reduction_fn() diff --git a/PyTorch/NLP/new-Transformer/fairseq/distributed/module_proxy_wrapper.py b/PyTorch/NLP/new-Transformer/fairseq/distributed/module_proxy_wrapper.py new file mode 100644 index 00000000..904dc0c2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/distributed/module_proxy_wrapper.py @@ -0,0 +1,56 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from torch import nn + + +class ModuleProxyWrapper(nn.Module): + """ + Wrap a DistributedDataParallel module and forward requests for missing + attributes to the module wrapped by DDP (the twice-wrapped module). + Also forward calls to :func:`state_dict` and :func:`load_state_dict`. + + Usage:: + + module.xyz = "hello world" + wrapped_module = DistributedDataParallel(module, **ddp_args) + wrapped_module = ModuleProxyWrapper(wrapped_module) + assert wrapped_module.xyz == "hello world" + assert wrapped_module.state_dict().keys() == module.state_dict().keys() + + Args: + module (nn.Module): module to wrap + """ + + def __init__(self, module: nn.Module): + super().__init__() + assert hasattr( + module, "module" + ), "ModuleProxyWrapper expects input to wrap another module" + self.module = module + + def __getattr__(self, name): + """Forward missing attributes to twice-wrapped module.""" + try: + # defer to nn.Module's logic + return super().__getattr__(name) + except AttributeError: + try: + # forward to the once-wrapped module + return getattr(self.module, name) + except AttributeError: + # forward to the twice-wrapped module + return getattr(self.module.module, name) + + def state_dict(self, *args, **kwargs): + """Forward to the twice-wrapped module.""" + return self.module.module.state_dict(*args, **kwargs) + + def load_state_dict(self, *args, **kwargs): + """Forward to the twice-wrapped module.""" + return self.module.module.load_state_dict(*args, **kwargs) + + def forward(self, *args, **kwargs): + return self.module(*args, **kwargs) diff --git a/PyTorch/NLP/new-Transformer/fairseq/distributed/tpu_distributed_data_parallel.py b/PyTorch/NLP/new-Transformer/fairseq/distributed/tpu_distributed_data_parallel.py new file mode 100644 index 00000000..3b9e1033 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/distributed/tpu_distributed_data_parallel.py @@ -0,0 +1,43 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from torch import nn + +from fairseq.distributed import utils + + +class TPUDistributedDataParallel(nn.Module): + def __init__(self, module, process_group): + super().__init__() + self.module = module + self.process_group = process_group + self.world_size = utils.get_world_size(self.process_group) + + def forward(self, *inputs, **kwargs): + return self.module(*inputs, **kwargs) + + def all_reduce_grads(self): + gradients = [] + for p in self.parameters(): + if not p.requires_grad: + continue + if p.grad is None: + p.grad = torch.zeros_like(p) + if p.grad.requires_grad: + raise RuntimeError( + "TPUDistributedDataParallel only works with gradients that don't " + "require grad" + ) + gradients.append(p.grad) + + import torch_xla.core.xla_model as xm + + xm.all_reduce( + "sum", + gradients, + scale=1.0 / self.world_size, + groups=self.process_group[1], + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/distributed/utils.py b/PyTorch/NLP/new-Transformer/fairseq/distributed/utils.py new file mode 100644 index 00000000..2c52f76a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/distributed/utils.py @@ -0,0 +1,808 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import io +import logging +import os +import pickle +import random +import socket +import struct +import subprocess +import warnings +from argparse import Namespace +from collections import OrderedDict +from dataclasses import dataclass +from typing import Any, Dict, List, Mapping, Optional + +import torch +import torch.distributed as dist +from fairseq.dataclass.configs import DistributedTrainingConfig, FairseqConfig +from omegaconf import open_dict + +try: + import torch_xla.core.xla_model as xm +except ImportError: + xm = None + + +# Flag to indicate if we're using Megatron +# NOTE: this is a temporary hack until we move away from Megatron's model parallel init +_USE_MEGATRON = False + +# Whether to use XLA ops (e.g., on TPUs) instead of CUDA ops. +_USE_XLA = False + + +logger = logging.getLogger(__name__) + + +def is_master(cfg: DistributedTrainingConfig): + return cfg.distributed_rank == 0 + + +def infer_init_method(cfg: DistributedTrainingConfig, force_distributed=False): + if cfg.distributed_init_method is not None or cfg.tpu: + return + + num_pipelines_per_node = None + if cfg.pipeline_model_parallel: + num_pipeline_devices, num_pipelines_per_node = _pipeline_parallel_pre_init(cfg) + + if all( + key in os.environ + for key in ["MASTER_ADDR", "MASTER_PORT", "WORLD_SIZE", "RANK"] + ): + # support torch.distributed.launch + _infer_torch_distributed_launch_init(cfg) + elif cfg.distributed_port > 0: + # we can determine the init method automatically for Slurm + _infer_slurm_init(cfg, num_pipelines_per_node) + elif cfg.distributed_world_size > 1 or force_distributed: + # fallback for single node with multiple GPUs + _infer_single_node_init(cfg) + + if cfg.pipeline_model_parallel: + _pipeline_parallel_post_init(cfg, num_pipeline_devices, num_pipelines_per_node) + elif not cfg.distributed_no_spawn: + with open_dict(cfg): + cfg.distributed_num_procs = min( + torch.cuda.device_count(), cfg.distributed_world_size + ) + + +def _infer_torch_distributed_launch_init(cfg: DistributedTrainingConfig): + cfg.distributed_init_method = "env://" + cfg.distributed_world_size = int(os.environ["WORLD_SIZE"]) + cfg.distributed_rank = int(os.environ["RANK"]) + # processes are created by torch.distributed.launch + cfg.distributed_no_spawn = True + + +def _infer_slurm_init(cfg: DistributedTrainingConfig, num_pipelines_per_node): + node_list = os.environ.get("SLURM_STEP_NODELIST") + if node_list is None: + node_list = os.environ.get("SLURM_JOB_NODELIST") + if node_list is not None: + try: + hostnames = subprocess.check_output( + ["scontrol", "show", "hostnames", node_list] + ) + cfg.distributed_init_method = "tcp://{host}:{port}".format( + host=hostnames.split()[0].decode("utf-8"), + port=cfg.distributed_port, + ) + nnodes = int(os.environ.get("SLURM_NNODES")) + ntasks_per_node = os.environ.get("SLURM_NTASKS_PER_NODE") + if ntasks_per_node is not None: + ntasks_per_node = int(ntasks_per_node) + else: + ntasks = int(os.environ.get("SLURM_NTASKS")) + nnodes = int(os.environ.get("SLURM_NNODES")) + assert ntasks % nnodes == 0 + ntasks_per_node = int(ntasks / nnodes) + if ntasks_per_node == 1: + gpus_per_node = torch.cuda.device_count() + node_id = int(os.environ.get("SLURM_NODEID")) + cfg.distributed_rank = node_id * gpus_per_node + cfg.distributed_world_size = nnodes * gpus_per_node + elif cfg.pipeline_model_parallel: + assert ntasks_per_node == num_pipelines_per_node, ( + "SLURM --ntasks-per-node must match number of pipelines per " + "node (={})".format(num_pipelines_per_node) + ) + cfg.distributed_no_spawn = True + # For 4-way MP on nodes with 8 GPUs, ranks will be [0, 1] on + # the first node, [1, 2] on the second node, etc. This + # matches torch.distributed.launch. + node_id = int(os.environ.get("SLURM_NODEID")) + local_id = int(os.environ.get("SLURM_LOCALID")) + cfg.distributed_rank = node_id * num_pipelines_per_node + local_id + # In the above example, device_id will always be in [0, 1], + # which also matches torch.distributed.launch. + cfg.device_id = local_id + # We also want to set distributed_world_size to be the total + # number of pipelines across all nodes. + cfg.distributed_world_size = nnodes * num_pipelines_per_node + else: + assert ntasks_per_node == cfg.distributed_world_size // nnodes + cfg.distributed_no_spawn = True + cfg.distributed_rank = int(os.environ.get("SLURM_PROCID")) + cfg.device_id = int(os.environ.get("SLURM_LOCALID")) + except subprocess.CalledProcessError as e: # scontrol failed + raise e + except FileNotFoundError: # Slurm is not installed + pass + + +def _infer_single_node_init(cfg: DistributedTrainingConfig): + assert ( + cfg.distributed_world_size <= torch.cuda.device_count() + ), f"world size is {cfg.distributed_world_size} but have {torch.cuda.device_count()} available devices" + port = random.randint(10000, 20000) + cfg.distributed_init_method = "tcp://localhost:{port}".format(port=port) + + +def _pipeline_parallel_pre_init(cfg: DistributedTrainingConfig): + from fairseq import utils + + balance_exists = ( + cfg.pipeline_balance is not None + or cfg.pipeline_encoder_balance is not None + or cfg.pipeline_decoder_balance is not None + ) + devices_exist = ( + cfg.pipeline_devices is not None + or cfg.pipeline_encoder_devices is not None + or cfg.pipeline_decoder_devices is not None + ) + if not balance_exists: + raise ValueError( + "--pipeline-balance is currently required for pipeline model parallelism" + ) + if not devices_exist: + raise ValueError( + "--pipeline-devices is currently required for pipeline model parallelism" + ) + + cfg.pipeline_balance = utils.eval_str_list(cfg.pipeline_balance, type=int) + if cfg.pipeline_devices is not None: + cfg.pipeline_devices = utils.eval_str_list(cfg.pipeline_devices, type=int) + num_pipeline_devices = len(set(cfg.pipeline_devices)) + else: + cfg.pipeline_encoder_devices = utils.eval_str_list( + cfg.pipeline_encoder_devices, type=int + ) + cfg.pipeline_decoder_devices = utils.eval_str_list( + cfg.pipeline_decoder_devices, type=int + ) + num_pipeline_devices = len( + set(cfg.pipeline_encoder_devices + cfg.pipeline_decoder_devices) + ) + gpus_per_node = torch.cuda.device_count() + assert ( + gpus_per_node >= num_pipeline_devices + and gpus_per_node % num_pipeline_devices == 0 + ), ( + "the number of unique device IDs in --pipeline-devices must evenly divide " + "the number of GPUs per node (multi-node pipelining is not yet supported)" + ) + num_pipelines_per_node = gpus_per_node // num_pipeline_devices + return num_pipeline_devices, num_pipelines_per_node + + +def _pipeline_parallel_post_init( + cfg: DistributedTrainingConfig, num_pipeline_devices, num_pipelines_per_node +): + if not cfg.distributed_no_spawn: + # When distributed_no_spawn is False, we expect distributed_rank and + # distributed_world_size to be based on the total number of GPUs, so + # we need to correct them to be based on the number of pipelines. + assert cfg.distributed_world_size % num_pipeline_devices == 0 + cfg.distributed_world_size = cfg.distributed_world_size // num_pipeline_devices + # In the case of 4-way MP on nodes with 8 GPUs, we want + # distributed_rank to be the starting GPU index for each pipeline + # i.e., 0, 2, ... + gpus_per_node = torch.cuda.device_count() + assert cfg.distributed_rank % gpus_per_node == 0 + assert cfg.distributed_rank % num_pipeline_devices == 0 + + with open_dict(cfg): + cfg.distributed_rank = cfg.distributed_rank // num_pipeline_devices + # launch one process per pipeline + cfg.distributed_num_procs = num_pipelines_per_node + + # if we have 4-way MP on a node with 8 GPUs, we want device_ids to be 0 + # and 4, indicating the starting device IDs for each pipeline + cfg.device_id *= num_pipeline_devices + + if cfg.device_id > 0: + # if there's multiple pipelines on a node (e.g., 4-way MP on an 8 + # GPU node), we need to adjust pipeline_devices accordingly + logger.debug( + "setting CUDA device={} on rank {}".format( + cfg.device_id, cfg.distributed_rank + ) + ) + torch.cuda.set_device(cfg.device_id) + with open_dict(cfg): + cfg.pipeline_devices = [cfg.device_id + d for d in cfg.pipeline_devices] + logger.info( + "setting pipeline_devices={} on rank {}".format( + cfg.pipeline_devices, cfg.distributed_rank + ) + ) + + +def distributed_init(cfg: FairseqConfig): + if isinstance(cfg, Namespace): + from fairseq.dataclass.utils import convert_namespace_to_omegaconf + + cfg = convert_namespace_to_omegaconf(cfg) + + if not cfg.common.tpu: + if torch.distributed.is_available() and torch.distributed.is_initialized(): + warnings.warn( + "Distributed is already initialized, cannot initialize twice!" + ) + else: + logger.info( + "distributed init (rank {}): {}".format( + cfg.distributed_training.distributed_rank, + cfg.distributed_training.distributed_init_method, + ) + ) + dist.init_process_group( + backend=cfg.distributed_training.distributed_backend, + init_method=cfg.distributed_training.distributed_init_method, + world_size=cfg.distributed_training.distributed_world_size, + rank=cfg.distributed_training.distributed_rank, + ) + logger.info( + "initialized host {} as rank {}".format( + socket.gethostname(), + cfg.distributed_training.distributed_rank, + ) + ) + + # perform a dummy all-reduce to initialize the NCCL communicator + if torch.cuda.is_available(): + dist.all_reduce(torch.zeros(1).cuda()) + + cfg.distributed_training.distributed_rank = torch.distributed.get_rank() + else: + assert xm.xrt_world_size() == cfg.distributed_training.distributed_world_size + global _USE_XLA + _USE_XLA = True + cfg.distributed_training.device_id = xm.get_local_ordinal() + cfg.distributed_training.distributed_rank = xm.get_ordinal() + xm.rendezvous("distributed_init") # wait for all workers + + if is_master(cfg.distributed_training): + logging.getLogger().setLevel(logging.INFO) + else: + logging.getLogger().setLevel(logging.WARNING) + + if cfg.common.model_parallel_size > 1: + try: + from fairseq.model_parallel.megatron.mpu import ( + initialize_model_parallel, + model_parallel_cuda_manual_seed, + ) + except ImportError: + raise ImportError( + "\n\nPlease install the megatron submodule:" + "\n\n git submodule update --init " + "fairseq/model_parallel/megatron" + ) + global _USE_MEGATRON + _USE_MEGATRON = True + initialize_model_parallel(cfg.common.model_parallel_size) + model_parallel_cuda_manual_seed(cfg.common.seed) + model_part_number = get_model_parallel_rank() + cfg.checkpoint.checkpoint_suffix += "-model_part-{0}".format(model_part_number) + + if hasattr(cfg, "model") and getattr(cfg.model, "base_layers", 0) > 0: + cfg.checkpoint.checkpoint_suffix = ( + f"-rank-{cfg.distributed_training.distributed_rank}" + ) + + return cfg.distributed_training.distributed_rank + + +def distributed_main(i, main, cfg: FairseqConfig, kwargs): + cfg.distributed_training.device_id = i + if torch.cuda.is_available() and not cfg.common.cpu and not cfg.common.tpu: + torch.cuda.set_device(cfg.distributed_training.device_id) + if cfg.distributed_training.distributed_rank is None: # torch.multiprocessing.spawn + cfg.distributed_training.distributed_rank = kwargs.pop("start_rank", 0) + i + + cfg.distributed_training.distributed_rank = distributed_init(cfg) + + after_distributed_init_fn = kwargs.pop("after_distributed_init_fn", None) + if after_distributed_init_fn: + cfg = after_distributed_init_fn(cfg) + + main(cfg, **kwargs) + + if torch.distributed.is_initialized(): + torch.distributed.barrier(get_global_group()) + + +def call_main(cfg: FairseqConfig, main, **kwargs): + if cfg.distributed_training.distributed_init_method is None: + infer_init_method(cfg.distributed_training) + + if cfg.distributed_training.distributed_init_method is not None: + # distributed training + if not cfg.distributed_training.distributed_no_spawn: + start_rank = cfg.distributed_training.distributed_rank + cfg.distributed_training.distributed_rank = None # assign automatically + kwargs["start_rank"] = start_rank + torch.multiprocessing.spawn( + fn=distributed_main, + args=(main, cfg, kwargs), + nprocs=min( + torch.cuda.device_count(), + cfg.distributed_training.distributed_world_size, + ), + join=True, + ) + else: + distributed_main(cfg.distributed_training.device_id, main, cfg, kwargs) + elif cfg.common.tpu and cfg.distributed_training.distributed_world_size > 1: + import torch_xla.distributed.xla_multiprocessing as xmp + + torch.multiprocessing.set_sharing_strategy("file_system") + xmp.spawn( + fn=distributed_main, + args=(main, cfg, kwargs), + # tpu-comment: + # 8 devices in one TPU VM, is the max processes to be spawned. + # The rest is driven by xm.distributed.xla_dist + nprocs=min(cfg.distributed_training.distributed_world_size, 8), + ) + else: + # single GPU main + main(cfg, **kwargs) + + +def use_xla(): + global _USE_XLA + return _USE_XLA + + +def new_groups(grouped_ranks: List[List[int]]): + if use_xla(): + return ("tpu", grouped_ranks) + else: + groups = [dist.new_group(g) for g in grouped_ranks] + my_group_idx = _find_my_group_index(grouped_ranks) + return groups[my_group_idx] + + +def _find_my_group_index(grouped_ranks): + my_rank = get_global_rank() + for i, group in enumerate(grouped_ranks): + if my_rank in group: + return i + raise RuntimeError + + +def _find_my_group(grouped_ranks): + index = _find_my_group_index(grouped_ranks) + return grouped_ranks[index] + + +def get_rank(group): + if use_xla(): + assert group[0] == "tpu" + my_group = _find_my_group(group[1]) + return my_group.index(get_global_rank()) + else: + return dist.get_rank(group=group) + + +def get_world_size(group): + if use_xla(): + assert group[0] == "tpu" + my_group = _find_my_group(group[1]) + return len(my_group) + elif torch.distributed.is_initialized(): + return dist.get_world_size(group=group) + else: + return 1 + + +def get_global_group(): + if use_xla(): + return new_groups([list(range(get_global_world_size()))]) + elif torch.distributed.is_initialized(): + if not hasattr(get_global_group, "_global_group"): + # ideally we could use torch.distributed.group.WORLD, but it seems + # to cause random NCCL hangs in some cases + get_global_group._global_group = dist.new_group() + return get_global_group._global_group + else: + return None + + +def get_global_rank(): + if use_xla(): + return xm.get_ordinal() + elif torch.distributed.is_initialized(): + return torch.distributed.get_rank() + else: + return 0 + + +def get_global_world_size(): + if use_xla(): + return xm.xrt_world_size() + elif torch.distributed.is_initialized(): + return torch.distributed.get_world_size() + else: + return 1 + + +def get_data_parallel_group(): + """Get the data parallel group the caller rank belongs to.""" + global _USE_MEGATRON + if _USE_MEGATRON: + from fairseq.model_parallel.megatron import mpu + + return mpu.get_data_parallel_group() + else: + return get_global_group() + + +def get_data_parallel_rank(): + """Return my rank for the data parallel group.""" + return get_rank(get_data_parallel_group()) + + +def get_data_parallel_world_size(): + """Return world size for the data parallel group.""" + return get_world_size(get_data_parallel_group()) + + +def get_model_parallel_group(): + global _USE_MEGATRON + if _USE_MEGATRON: + from fairseq.model_parallel.megatron import mpu + + return mpu.get_model_parallel_group() + else: + return None + + +def get_model_parallel_rank(): + """Return my rank for the model parallel group.""" + return get_rank(get_model_parallel_group()) + + +def get_model_parallel_world_size(): + """Return world size for the model parallel group.""" + return get_world_size(get_model_parallel_group()) + + +def all_reduce(tensor, group, op="sum"): + if use_xla(): + assert isinstance(group, tuple) and group[0] == "tpu" + tensor = [tensor] # wrap in a list to make xm.all_reduce in-place + return xm.all_reduce(op, tensor, groups=group[1])[0] + else: + if op == "sum": + op = dist.ReduceOp.SUM + elif op == "max": + op = dist.ReduceOp.MAX + else: + raise NotImplementedError + dist.all_reduce(tensor, op=op, group=group) + return tensor + + +def broadcast(tensor, src, group): + if use_xla(): + # XLA doesn't support broadcast, hack it with all_reduce + if get_rank(group) != src: + tensor.zero_() + all_reduce(tensor, group) + else: + dist.broadcast(tensor, src=src, group=group) + + +def all_to_all(tensor, group): + """Perform an all-to-all operation on a 1D Tensor.""" + assert tensor.dim() == 1 + split_count = get_world_size(group=group) + assert tensor.numel() % split_count == 0 + if use_xla(): + assert isinstance(group, tuple) and group[0] == "tpu" + return xm.all_to_all( + tensor, + split_dimension=0, + concat_dimension=0, + split_count=split_count, + groups=group[1], + ) + else: + output = torch.zeros_like(tensor) + dist.all_to_all_single(output, tensor, group=group) + return output + + +def all_gather(tensor, group, return_tensor=False): + """Perform an all-gather operation.""" + if use_xla(): + result = xm.all_gather(tensor, groups=group[1]) + world_size = get_world_size(group=group) + result = result.view(world_size, *tensor.size()) + if return_tensor: + return result + else: + return [result[i] for i in range(world_size)] + else: + world_size = get_world_size(group=group) + rank = get_rank(group=group) + tensor_list = [ + tensor if i == rank else torch.empty_like(tensor) for i in range(world_size) + ] + dist.all_gather(tensor_list, tensor, group=group) + if return_tensor: + return torch.stack(tensor_list, dim=0) + else: + return tensor_list + + +def all_gather_list(data, group=None, max_size=16384): + """Gathers arbitrary data from all nodes into a list. + + Similar to :func:`~torch.distributed.all_gather` but for arbitrary Python + data. Note that *data* must be picklable and any CUDA tensors will be moved + to CPU and returned on CPU as well. + + Args: + data (Any): data from the local worker to be gathered on other workers + group: group of the collective + max_size (int, optional): maximum size of the data to be gathered + across workers + """ + from fairseq import utils + + if group is None: + group = get_global_group() + rank = get_rank(group=group) + world_size = get_world_size(group=group) + + buffer_size = max_size * world_size + if ( + not hasattr(all_gather_list, "_buffer") + or all_gather_list._buffer.numel() < buffer_size + ): + all_gather_list._buffer = torch.cuda.ByteTensor(buffer_size) + all_gather_list._cpu_buffer = torch.ByteTensor(max_size).pin_memory() + buffer = all_gather_list._buffer + buffer.zero_() + cpu_buffer = all_gather_list._cpu_buffer + + data = utils.move_to_cpu(data) + enc = pickle.dumps(data) + enc_size = len(enc) + header_size = 4 # size of header that contains the length of the encoded data + size = header_size + enc_size + if size > max_size: + raise ValueError( + "encoded data size ({}) exceeds max_size ({})".format(size, max_size) + ) + + header = struct.pack(">I", enc_size) + cpu_buffer[:size] = torch.ByteTensor(list(header + enc)) + start = rank * max_size + buffer[start : start + size].copy_(cpu_buffer[:size]) + + all_reduce(buffer, group=group) + + buffer = buffer.cpu() + try: + result = [] + for i in range(world_size): + out_buffer = buffer[i * max_size : (i + 1) * max_size] + (enc_size,) = struct.unpack(">I", bytes(out_buffer[:header_size].tolist())) + if enc_size > 0: + result.append( + pickle.loads( + bytes(out_buffer[header_size : header_size + enc_size].tolist()) + ) + ) + return result + except pickle.UnpicklingError: + raise Exception( + "Unable to unpickle data from other workers. all_gather_list requires all " + "workers to enter the function together, so this error usually indicates " + "that the workers have fallen out of sync somehow. Workers can fall out of " + "sync if one of them runs out of memory, or if there are other conditions " + "in your training script that can cause one worker to finish an epoch " + "while other workers are still iterating over their portions of the data. " + "Try rerunning with --ddp-backend=legacy_ddp and see if that helps." + ) + + +def all_reduce_dict(data: Mapping[str, Any], device, group) -> Dict[str, Any]: + """ + AllReduce a dictionary of values across workers. We separately + reduce items that are already on the device and items on CPU for + better performance. + + Args: + data (Mapping[str, Any]): dictionary of data to all-reduce, but + cannot be a nested dictionary + device (torch.device): device for the reduction + group: group of the collective + """ + data_keys = list(data.keys()) + + # We want to separately reduce items that are already on the + # device and items on CPU for performance reasons. + cpu_data = OrderedDict() + device_data = OrderedDict() + for k in data_keys: + t = data[k] + if not torch.is_tensor(t): + cpu_data[k] = torch.tensor(t, dtype=torch.double) + elif t.device.type != device.type: + cpu_data[k] = t.to(dtype=torch.double) + else: + device_data[k] = t.to(dtype=torch.double) + + def _all_reduce_dict(data: OrderedDict): + if len(data) == 0: + return data + buf = torch.cat([t.view(-1) for t in data.values()]).to(device=device) + all_reduce(buf, group=group) + split_buf = torch.split(buf.clone(), [t.numel() for t in data.values()]) + reduced_data = [t.view_as(orig) for t, orig in zip(split_buf, data.values())] + return OrderedDict(zip(data.keys(), reduced_data)) + + cpu_data = _all_reduce_dict(cpu_data) + device_data = _all_reduce_dict(device_data) + + def get_from_stack(key): + if key in cpu_data: + return cpu_data[key] + elif key in device_data: + return device_data[key] + raise KeyError + + return OrderedDict([(key, get_from_stack(key)) for key in data_keys]) + + +def broadcast_tensors( + tensors: Optional[List[torch.Tensor]], + src_rank: int, + group: object, + dist_device: Optional[torch.device] = None, +) -> List[torch.Tensor]: + """ + Broadcasts a list of tensors without other (non-src) ranks needing to know + the dtypes/shapes of the tensors. + """ + if dist_device is None: + if torch.distributed.get_backend(group) == "nccl": + dist_device = torch.device("cuda") + else: + dist_device = torch.device("cpu") + + # share metadata first to simplify transfer + is_src_rank = get_rank(group) == src_rank + if is_src_rank: + metadata = [ + {"size": t.size(), "dtype": t.dtype, "device": t.device} for t in tensors + ] + metadata = _broadcast_object_slow(metadata, src_rank, group, dist_device) + else: + metadata = _broadcast_object_slow(None, src_rank, group, dist_device) + + out_tensors = [] + for i, meta in enumerate(metadata): + if is_src_rank: + tensor = tensors[i] + broadcast(tensors[i].to(dist_device), src=src_rank, group=group) + else: + tensor = torch.zeros( + [meta["size"].numel()], dtype=meta["dtype"], device=dist_device + ) + broadcast(tensor, src=src_rank, group=group) + tensor = tensor.view(meta["size"]).to(meta["device"]) + out_tensors.append(tensor) + return out_tensors + + +def broadcast_object( + obj: Any, + src_rank: int, + group: object, + dist_device: Optional[torch.device] = None, +) -> Any: + """Broadcast an arbitrary Python object to other workers.""" + if dist_device is None: + if torch.distributed.get_backend(group) == "nccl": + dist_device = torch.device("cuda") + else: + dist_device = torch.device("cpu") + + if get_rank(group) == src_rank: + # split the tensors from the non-tensors so we can broadcast them + # directly, avoiding unnecessary serialization/deserialization + tensors = [] + obj = _split_tensors_from_obj(obj, tensors) + obj = _broadcast_object_slow(obj, src_rank, group, dist_device) + tensors = broadcast_tensors(tensors, src_rank, group, dist_device) + else: + obj = _broadcast_object_slow(None, src_rank, group, dist_device) + tensors = broadcast_tensors(None, src_rank, group, dist_device) + return _put_tensors_in_obj(obj, tensors) + + +def _broadcast_object_slow( + obj: Any, + src_rank: int, + group: object, + dist_device: torch.device, +) -> Any: + if get_rank(group) == src_rank: + # Emit data + buffer = io.BytesIO() + torch.save(obj, buffer) + buffer = torch.ByteTensor(buffer.getbuffer()).to(dist_device) + length = torch.LongTensor([len(buffer)]).to(dist_device) + broadcast(length, src=src_rank, group=group) + broadcast(buffer, src=src_rank, group=group) + else: + # Fetch from the source + length = torch.LongTensor([0]).to(dist_device) + broadcast(length, src=src_rank, group=group) + buffer = torch.ByteTensor(int(length.item())).to(dist_device) + broadcast(buffer, src=src_rank, group=group) + buffer = io.BytesIO(buffer.cpu().numpy()) + obj = torch.load(buffer, map_location="cpu") + return obj + + +@dataclass(frozen=True) +class _TensorPlaceholder: + index: int + + +def _split_tensors_from_obj(obj: Any, tensors: List[torch.Tensor]) -> Any: + if torch.is_tensor(obj): + placeholder = _TensorPlaceholder(index=len(tensors)) + tensors.append(obj) + return placeholder + elif isinstance(obj, dict): + return {k: _split_tensors_from_obj(v, tensors) for k, v in obj.items()} + elif isinstance(obj, list): + return [_split_tensors_from_obj(v, tensors) for v in obj] + elif isinstance(obj, tuple): + return tuple(_split_tensors_from_obj(v, tensors) for v in obj) + elif isinstance(obj, set): + return {_split_tensors_from_obj(v, tensors) for v in obj} + else: + return obj + + +def _put_tensors_in_obj(obj: Any, tensors: List[torch.Tensor]) -> Any: + if isinstance(obj, _TensorPlaceholder): + return tensors[obj.index] + elif isinstance(obj, dict): + return {k: _put_tensors_in_obj(v, tensors) for k, v in obj.items()} + elif isinstance(obj, list): + return [_put_tensors_in_obj(v, tensors) for v in obj] + elif isinstance(obj, tuple): + return tuple(_put_tensors_in_obj(v, tensors) for v in obj) + elif isinstance(obj, set): + return {_put_tensors_in_obj(v, tensors) for v in obj} + else: + return obj diff --git a/PyTorch/NLP/new-Transformer/fairseq/file_chunker_utils.py b/PyTorch/NLP/new-Transformer/fairseq/file_chunker_utils.py new file mode 100644 index 00000000..3f275490 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/file_chunker_utils.py @@ -0,0 +1,84 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import os +import typing as tp + + +def _safe_readline(fd) -> str: + pos = fd.tell() + while True: + try: + return fd.readline() + except UnicodeDecodeError: + pos -= 1 + fd.seek(pos) # search where this character begins + + +def find_offsets(filename: str, num_chunks: int) -> tp.List[int]: + """ + given a file and a number of chuncks, find the offsets in the file + to be able to chunk around full lines. + """ + with open(filename, "r", encoding="utf-8") as f: + size = os.fstat(f.fileno()).st_size + chunk_size = size // num_chunks + offsets = [0 for _ in range(num_chunks + 1)] + for i in range(1, num_chunks): + f.seek(chunk_size * i) + _safe_readline(f) + offsets[i] = f.tell() + offsets[-1] = size + return offsets + + +class ChunkLineIterator: + """ + Iterator to properly iterate over lines of a file chunck. + """ + + def __init__(self, fd, start_offset: int, end_offset: int): + self._fd = fd + self._start_offset = start_offset + self._end_offset = end_offset + + def __iter__(self) -> tp.Iterable[str]: + self._fd.seek(self._start_offset) + # next(f) breaks f.tell(), hence readline() must be used + line = _safe_readline(self._fd) + while line: + pos = self._fd.tell() + # f.tell() does not always give the byte position in the file + # sometimes it skips to a very large number + # it is unlikely that through a normal read we go from + # end bytes to end + 2**32 bytes (4 GB) and this makes it unlikely + # that the procedure breaks by the undeterministic behavior of + # f.tell() + if ( + self._end_offset > 0 + and pos > self._end_offset + and pos < self._end_offset + 2**32 + ): + break + yield line + line = self._fd.readline() + + +class Chunker: + """ + contextmanager to read a chunck of a file line by line. + """ + + def __init__(self, path: str, start_offset: int, end_offset: int): + self.path = path + self.start_offset = start_offset + self.end_offset = end_offset + + def __enter__(self) -> ChunkLineIterator: + self.fd = open(self.path, "r", encoding="utf-8") + return ChunkLineIterator(self.fd, self.start_offset, self.end_offset) + + def __exit__(self, exc_type, exc_val, exc_tb) -> None: + self.fd.close() diff --git a/PyTorch/NLP/new-Transformer/fairseq/file_io.py b/PyTorch/NLP/new-Transformer/fairseq/file_io.py new file mode 100644 index 00000000..8eca70a0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/file_io.py @@ -0,0 +1,196 @@ +#!/usr/bin/env python3 + +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +import shutil +from typing import List, Optional + + +logger = logging.getLogger(__file__) + + +try: + from iopath.common.file_io import g_pathmgr as IOPathManager + + try: + # [FB only - for now] AWS PathHandler for PathManager + from .fb_pathhandlers import S3PathHandler + + IOPathManager.register_handler(S3PathHandler()) + except KeyError: + logging.warning("S3PathHandler already registered.") + except ImportError: + logging.debug( + "S3PathHandler couldn't be imported. Either missing fb-only files, or boto3 module." + ) + +except ImportError: + IOPathManager = None + + +class PathManager: + """ + Wrapper for insulating OSS I/O (using Python builtin operations) from + iopath's PathManager abstraction (for transparently handling various + internal backends). + """ + + @staticmethod + def open( + path: str, + mode: str = "r", + buffering: int = -1, + encoding: Optional[str] = None, + errors: Optional[str] = None, + newline: Optional[str] = None, + ): + if IOPathManager: + return IOPathManager.open( + path=path, + mode=mode, + buffering=buffering, + encoding=encoding, + errors=errors, + newline=newline, + ) + return open( + path, + mode=mode, + buffering=buffering, + encoding=encoding, + errors=errors, + newline=newline, + ) + + @staticmethod + def copy(src_path: str, dst_path: str, overwrite: bool = False) -> bool: + if IOPathManager: + return IOPathManager.copy( + src_path=src_path, dst_path=dst_path, overwrite=overwrite + ) + return shutil.copyfile(src_path, dst_path) + + @staticmethod + def get_local_path(path: str, **kwargs) -> str: + if IOPathManager: + return IOPathManager.get_local_path(path, **kwargs) + return path + + @staticmethod + def exists(path: str) -> bool: + if IOPathManager: + return IOPathManager.exists(path) + return os.path.exists(path) + + @staticmethod + def isfile(path: str) -> bool: + if IOPathManager: + return IOPathManager.isfile(path) + return os.path.isfile(path) + + @staticmethod + def ls(path: str) -> List[str]: + if IOPathManager: + return IOPathManager.ls(path) + return os.listdir(path) + + @staticmethod + def mkdirs(path: str) -> None: + if IOPathManager: + return IOPathManager.mkdirs(path) + os.makedirs(path, exist_ok=True) + + @staticmethod + def rm(path: str) -> None: + if IOPathManager: + return IOPathManager.rm(path) + os.remove(path) + + @staticmethod + def chmod(path: str, mode: int) -> None: + if not PathManager.path_requires_pathmanager(path): + os.chmod(path, mode) + + @staticmethod + def register_handler(handler) -> None: + if IOPathManager: + return IOPathManager.register_handler(handler=handler) + + @staticmethod + def copy_from_local( + local_path: str, dst_path: str, overwrite: bool = False, **kwargs + ) -> None: + if IOPathManager: + return IOPathManager.copy_from_local( + local_path=local_path, dst_path=dst_path, overwrite=overwrite, **kwargs + ) + return shutil.copyfile(local_path, dst_path) + + @staticmethod + def path_requires_pathmanager(path: str) -> bool: + """Do we require PathManager to access given path?""" + if IOPathManager: + for p in IOPathManager._path_handlers.keys(): + if path.startswith(p): + return True + return False + + @staticmethod + def supports_rename(path: str) -> bool: + # PathManager doesn't yet support renames + return not PathManager.path_requires_pathmanager(path) + + @staticmethod + def rename(src: str, dst: str): + os.rename(src, dst) + + """ + ioPath async PathManager methods: + """ + + @staticmethod + def opena( + path: str, + mode: str = "r", + buffering: int = -1, + encoding: Optional[str] = None, + errors: Optional[str] = None, + newline: Optional[str] = None, + ): + """ + Return file descriptor with asynchronous write operations. + """ + global IOPathManager + if not IOPathManager: + logging.info("ioPath is initializing PathManager.") + try: + from iopath.common.file_io import PathManager + + IOPathManager = PathManager() + except Exception: + logging.exception("Failed to initialize ioPath PathManager object.") + return IOPathManager.opena( + path=path, + mode=mode, + buffering=buffering, + encoding=encoding, + errors=errors, + newline=newline, + ) + + @staticmethod + def async_close() -> bool: + """ + Wait for files to be written and clean up asynchronous PathManager. + NOTE: `PathManager.async_close()` must be called at the end of any + script that uses `PathManager.opena(...)`. + """ + global IOPathManager + if IOPathManager: + return IOPathManager.async_close() + return False diff --git a/PyTorch/NLP/new-Transformer/fairseq/file_utils.py b/PyTorch/NLP/new-Transformer/fairseq/file_utils.py new file mode 100644 index 00000000..b99da2e8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/file_utils.py @@ -0,0 +1,370 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +""" +Utilities for working with the local dataset cache. +This file is adapted from `AllenNLP `_. +and `huggingface `_. +""" + +import fnmatch +import json +import logging +import os +import shutil +import tarfile +import tempfile +from functools import partial, wraps +from hashlib import sha256 +from io import open + + +try: + from torch.hub import _get_torch_home + + torch_cache_home = _get_torch_home() +except ImportError: + torch_cache_home = os.path.expanduser( + os.getenv( + "TORCH_HOME", os.path.join(os.getenv("XDG_CACHE_HOME", "~/.cache"), "torch") + ) + ) +default_cache_path = os.path.join(torch_cache_home, "pytorch_fairseq") + +try: + from urllib.parse import urlparse +except ImportError: + from urlparse import urlparse + +try: + from pathlib import Path + + PYTORCH_FAIRSEQ_CACHE = Path(os.getenv("PYTORCH_FAIRSEQ_CACHE", default_cache_path)) +except (AttributeError, ImportError): + PYTORCH_FAIRSEQ_CACHE = os.getenv("PYTORCH_FAIRSEQ_CACHE", default_cache_path) + +CONFIG_NAME = "config.json" +WEIGHTS_NAME = "pytorch_model.bin" + +logger = logging.getLogger(__name__) # pylint: disable=invalid-name + + +def load_archive_file(archive_file): + # redirect to the cache, if necessary + try: + resolved_archive_file = cached_path(archive_file, cache_dir=None) + except EnvironmentError: + logger.info( + "Archive name '{}' was not found in archive name list. " + "We assumed '{}' was a path or URL but couldn't find any file " + "associated to this path or URL.".format( + archive_file, + archive_file, + ) + ) + return None + + if resolved_archive_file == archive_file: + logger.info("loading archive file {}".format(archive_file)) + else: + logger.info( + "loading archive file {} from cache at {}".format( + archive_file, resolved_archive_file + ) + ) + + # Extract archive to temp dir and replace .tar.bz2 if necessary + tempdir = None + if not os.path.isdir(resolved_archive_file): + tempdir = tempfile.mkdtemp() + logger.info( + "extracting archive file {} to temp dir {}".format( + resolved_archive_file, tempdir + ) + ) + ext = os.path.splitext(archive_file)[1][1:] + with tarfile.open(resolved_archive_file, "r:" + ext) as archive: + top_dir = os.path.commonprefix(archive.getnames()) + archive.extractall(tempdir) + os.remove(resolved_archive_file) + shutil.move(os.path.join(tempdir, top_dir), resolved_archive_file) + shutil.rmtree(tempdir) + + return resolved_archive_file + + +def url_to_filename(url, etag=None): + """ + Convert `url` into a hashed filename in a repeatable way. + If `etag` is specified, append its hash to the URL's, delimited + by a period. + """ + url_bytes = url.encode("utf-8") + url_hash = sha256(url_bytes) + filename = url_hash.hexdigest() + + if etag: + etag_bytes = etag.encode("utf-8") + etag_hash = sha256(etag_bytes) + filename += "." + etag_hash.hexdigest() + + return filename + + +def filename_to_url(filename, cache_dir=None): + """ + Return the url and etag (which may be ``None``) stored for `filename`. + Raise ``EnvironmentError`` if `filename` or its stored metadata do not exist. + """ + if cache_dir is None: + cache_dir = PYTORCH_FAIRSEQ_CACHE + if isinstance(cache_dir, Path): + cache_dir = str(cache_dir) + + cache_path = os.path.join(cache_dir, filename) + if not os.path.exists(cache_path): + raise EnvironmentError("file {} not found".format(cache_path)) + + meta_path = cache_path + ".json" + if not os.path.exists(meta_path): + raise EnvironmentError("file {} not found".format(meta_path)) + + with open(meta_path, encoding="utf-8") as meta_file: + metadata = json.load(meta_file) + url = metadata["url"] + etag = metadata["etag"] + + return url, etag + + +def cached_path_from_pm(url_or_filename): + """ + Tries to cache the specified URL using PathManager class. + Returns the cached path if success otherwise failure. + """ + try: + from fairseq.file_io import PathManager + + local_path = PathManager.get_local_path(url_or_filename) + return local_path + except Exception: + return None + + +def cached_path(url_or_filename, cache_dir=None): + """ + Given something that might be a URL (or might be a local path), + determine which. If it's a URL, download the file and cache it, and + return the path to the cached file. If it's already a local path, + make sure the file exists and then return the path. + """ + if cache_dir is None: + cache_dir = PYTORCH_FAIRSEQ_CACHE + if isinstance(url_or_filename, Path): + url_or_filename = str(url_or_filename) + if isinstance(cache_dir, Path): + cache_dir = str(cache_dir) + + parsed = urlparse(url_or_filename) + + if parsed.scheme in ("http", "https", "s3"): + # URL, so get it from the cache (downloading if necessary) + return get_from_cache(url_or_filename, cache_dir) + elif os.path.exists(url_or_filename): + # File, and it exists. + return url_or_filename + elif parsed.scheme == "": + # File, but it doesn't exist. + raise EnvironmentError("file {} not found".format(url_or_filename)) + else: + cached_path = cached_path_from_pm(url_or_filename) + if cached_path: + return cached_path + # Something unknown + raise ValueError( + "unable to parse {} as a URL or as a local path".format(url_or_filename) + ) + + +def split_s3_path(url): + """Split a full s3 path into the bucket name and path.""" + parsed = urlparse(url) + if not parsed.netloc or not parsed.path: + raise ValueError("bad s3 path {}".format(url)) + bucket_name = parsed.netloc + s3_path = parsed.path + # Remove '/' at beginning of path. + if s3_path.startswith("/"): + s3_path = s3_path[1:] + return bucket_name, s3_path + + +def s3_request(func): + """ + Wrapper function for s3 requests in order to create more helpful error + messages. + """ + + @wraps(func) + def wrapper(url, *args, **kwargs): + from botocore.exceptions import ClientError + + try: + return func(url, *args, **kwargs) + except ClientError as exc: + if int(exc.response["Error"]["Code"]) == 404: + raise EnvironmentError("file {} not found".format(url)) + else: + raise + + return wrapper + + +@s3_request +def s3_etag(url): + """Check ETag on S3 object.""" + import boto3 + + s3_resource = boto3.resource("s3") + bucket_name, s3_path = split_s3_path(url) + s3_object = s3_resource.Object(bucket_name, s3_path) + return s3_object.e_tag + + +@s3_request +def s3_get(url, temp_file): + """Pull a file directly from S3.""" + import boto3 + + s3_resource = boto3.resource("s3") + bucket_name, s3_path = split_s3_path(url) + s3_resource.Bucket(bucket_name).download_fileobj(s3_path, temp_file) + + +def request_wrap_timeout(func, url): + import requests + + for attempt, timeout in enumerate([10, 20, 40, 60, 60]): + try: + return func(timeout=timeout) + except requests.exceptions.Timeout as e: + logger.warning( + "Request for %s timed-out (attempt %d). Retrying with a timeout of %d secs", + url, + attempt, + timeout, + exc_info=e, + ) + continue + raise RuntimeError(f"Unable to fetch file {url}") + + +def http_get(url, temp_file): + import requests + from tqdm import tqdm + + req = request_wrap_timeout(partial(requests.get, url, stream=True), url) + content_length = req.headers.get("Content-Length") + total = int(content_length) if content_length is not None else None + progress = tqdm(unit="B", total=total) + for chunk in req.iter_content(chunk_size=1024): + if chunk: # filter out keep-alive new chunks + progress.update(len(chunk)) + temp_file.write(chunk) + progress.close() + + +def get_from_cache(url, cache_dir=None): + """ + Given a URL, look for the corresponding dataset in the local cache. + If it's not there, download it. Then return the path to the cached file. + """ + if cache_dir is None: + cache_dir = PYTORCH_FAIRSEQ_CACHE + if isinstance(cache_dir, Path): + cache_dir = str(cache_dir) + + if not os.path.exists(cache_dir): + os.makedirs(cache_dir) + + # Get eTag to add to filename, if it exists. + if url.startswith("s3://"): + etag = s3_etag(url) + else: + try: + import requests + + response = request_wrap_timeout( + partial(requests.head, url, allow_redirects=True), url + ) + if response.status_code != 200: + etag = None + else: + etag = response.headers.get("ETag") + except RuntimeError: + etag = None + + filename = url_to_filename(url, etag) + + # get cache path to put the file + cache_path = os.path.join(cache_dir, filename) + + # If we don't have a connection (etag is None) and can't identify the file + # try to get the last downloaded one + if not os.path.exists(cache_path) and etag is None: + matching_files = fnmatch.filter(os.listdir(cache_dir), filename + ".*") + matching_files = list(filter(lambda s: not s.endswith(".json"), matching_files)) + if matching_files: + cache_path = os.path.join(cache_dir, matching_files[-1]) + + if not os.path.exists(cache_path): + # Download to temporary file, then copy to cache dir once finished. + # Otherwise you get corrupt cache entries if the download gets interrupted. + with tempfile.NamedTemporaryFile() as temp_file: + logger.info("%s not found in cache, downloading to %s", url, temp_file.name) + + # GET file object + if url.startswith("s3://"): + s3_get(url, temp_file) + else: + http_get(url, temp_file) + + # we are copying the file before closing it, so flush to avoid truncation + temp_file.flush() + # shutil.copyfileobj() starts at the current position, so go to the start + temp_file.seek(0) + + logger.info("copying %s to cache at %s", temp_file.name, cache_path) + with open(cache_path, "wb") as cache_file: + shutil.copyfileobj(temp_file, cache_file) + + logger.info("creating metadata file for %s", cache_path) + meta = {"url": url, "etag": etag} + meta_path = cache_path + ".json" + with open(meta_path, "w") as meta_file: + output_string = json.dumps(meta) + meta_file.write(output_string) + + logger.info("removing temp file %s", temp_file.name) + + return cache_path + + +def read_set_from_file(filename): + """ + Extract a de-duped collection (set) of text from a file. + Expected file format is one item per line. + """ + collection = set() + with open(filename, "r", encoding="utf-8") as file_: + for line in file_: + collection.add(line.rstrip()) + return collection + + +def get_file_extension(path, dot=True, lower=True): + ext = os.path.splitext(path)[1] + ext = ext if dot else ext[1:] + return ext.lower() if lower else ext diff --git a/PyTorch/NLP/new-Transformer/fairseq/hub_utils.py b/PyTorch/NLP/new-Transformer/fairseq/hub_utils.py new file mode 100644 index 00000000..b6fa2cb9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/hub_utils.py @@ -0,0 +1,314 @@ +#!/usr/bin/env python3 -u +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import argparse +import copy +import logging +import os +from typing import Any, Dict, Iterator, List + +import torch +from omegaconf import open_dict +from torch import nn + +from fairseq import utils +from fairseq.data import encoders + +logger = logging.getLogger(__name__) + + +def from_pretrained( + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + archive_map=None, + **kwargs +): + from fairseq import checkpoint_utils, file_utils + + if archive_map is not None: + if model_name_or_path in archive_map: + model_name_or_path = archive_map[model_name_or_path] + if data_name_or_path is not None and data_name_or_path in archive_map: + data_name_or_path = archive_map[data_name_or_path] + + # allow archive_map to set default arg_overrides (e.g., tokenizer, bpe) + # for each model + if isinstance(model_name_or_path, dict): + for k, v in model_name_or_path.items(): + if k == "checkpoint_file": + checkpoint_file = v + elif ( + k != "path" + # only set kwargs that don't already have overrides + and k not in kwargs + ): + kwargs[k] = v + model_name_or_path = model_name_or_path["path"] + + model_path = file_utils.load_archive_file(model_name_or_path) + + # convenience hack for loading data and BPE codes from model archive + if data_name_or_path.startswith("."): + kwargs["data"] = os.path.abspath(os.path.join(model_path, data_name_or_path)) + else: + kwargs["data"] = file_utils.load_archive_file(data_name_or_path) + for file, arg in { + "code": "bpe_codes", + "bpecodes": "bpe_codes", + "sentencepiece.bpe.model": "sentencepiece_model", + "merges.txt": "bpe_merges", + "vocab.json": "bpe_vocab", + }.items(): + path = os.path.join(model_path, file) + if os.path.exists(path): + kwargs[arg] = path + + if "user_dir" in kwargs: + utils.import_user_module(argparse.Namespace(user_dir=kwargs["user_dir"])) + + models, args, task = checkpoint_utils.load_model_ensemble_and_task( + [os.path.join(model_path, cpt) for cpt in checkpoint_file.split(os.pathsep)], + arg_overrides=kwargs, + ) + + return { + "args": args, + "task": task, + "models": models, + } + + +class GeneratorHubInterface(nn.Module): + """ + PyTorch Hub interface for generating sequences from a pre-trained + translation or language model. + """ + + def __init__(self, cfg, task, models): + super().__init__() + self.cfg = cfg + self.task = task + self.models = nn.ModuleList(models) + self.src_dict = task.source_dictionary + self.tgt_dict = task.target_dictionary + + # optimize model for generation + for model in self.models: + model.prepare_for_inference_(cfg) + + # Load alignment dictionary for unknown word replacement + # (None if no unknown word replacement, empty if no path to align dictionary) + self.align_dict = utils.load_align_dict(cfg.generation.replace_unk) + + self.tokenizer = encoders.build_tokenizer(cfg.tokenizer) + self.bpe = encoders.build_bpe(cfg.bpe) + + self.max_positions = utils.resolve_max_positions( + self.task.max_positions(), *[model.max_positions() for model in models] + ) + + # this is useful for determining the device + self.register_buffer("_float_tensor", torch.tensor([0], dtype=torch.float)) + + @property + def device(self): + return self._float_tensor.device + + def translate( + self, sentences: List[str], beam: int = 5, verbose: bool = False, **kwargs + ) -> List[str]: + return self.sample(sentences, beam, verbose, **kwargs) + + def sample( + self, sentences: List[str], beam: int = 1, verbose: bool = False, **kwargs + ) -> List[str]: + if isinstance(sentences, str): + return self.sample([sentences], beam=beam, verbose=verbose, **kwargs)[0] + tokenized_sentences = [self.encode(sentence) for sentence in sentences] + batched_hypos = self.generate(tokenized_sentences, beam, verbose, **kwargs) + return [self.decode(hypos[0]["tokens"]) for hypos in batched_hypos] + + def score( + self, sentences: List[str], replace_newline_with_eos: bool = False, **kwargs + ): + if isinstance(sentences, str): + return self.score( + [sentences], replace_newline_with_eos=replace_newline_with_eos, **kwargs + )[0] + + def encode(sentence): + if replace_newline_with_eos: + return torch.cat([self.encode(line) for line in sentence.splitlines()]) + else: + return self.encode(sentence) + + # NOTE: this doesn't support translation tasks currently + tokenized_sentences = [encode(sentence) for sentence in sentences] + return [ + hypos[0] + for hypos in self.generate( + tokenized_sentences, score_reference=True, **kwargs + ) + ] + + def generate( + self, + tokenized_sentences: List[torch.LongTensor], + beam: int = 5, + verbose: bool = False, + skip_invalid_size_inputs=False, + inference_step_args=None, + prefix_allowed_tokens_fn=None, + **kwargs + ) -> List[List[Dict[str, torch.Tensor]]]: + if torch.is_tensor(tokenized_sentences) and tokenized_sentences.dim() == 1: + return self.generate( + tokenized_sentences.unsqueeze(0), beam=beam, verbose=verbose, **kwargs + )[0] + + # build generator using current args as well as any kwargs + gen_args = copy.deepcopy(self.cfg.generation) + with open_dict(gen_args): + gen_args.beam = beam + for k, v in kwargs.items(): + setattr(gen_args, k, v) + generator = self.task.build_generator( + self.models, + gen_args, + prefix_allowed_tokens_fn=prefix_allowed_tokens_fn, + ) + + inference_step_args = inference_step_args or {} + results = [] + for batch in self._build_batches(tokenized_sentences, skip_invalid_size_inputs): + batch = utils.apply_to_sample(lambda t: t.to(self.device), batch) + translations = self.task.inference_step( + generator, self.models, batch, **inference_step_args + ) + for id, hypos in zip(batch["id"].tolist(), translations): + results.append((id, hypos)) + + # sort output to match input order + outputs = [hypos for _, hypos in sorted(results, key=lambda x: x[0])] + + if verbose: + + def getarg(name, default): + return getattr(gen_args, name, getattr(self.cfg, name, default)) + + for source_tokens, target_hypotheses in zip(tokenized_sentences, outputs): + src_str_with_unk = self.string(source_tokens) + logger.info("S\t{}".format(src_str_with_unk)) + for hypo in target_hypotheses: + hypo_str = self.decode(hypo["tokens"]) + logger.info("H\t{}\t{}".format(hypo["score"], hypo_str)) + logger.info( + "P\t{}".format( + " ".join( + map( + lambda x: "{:.4f}".format(x), + hypo["positional_scores"].tolist(), + ) + ) + ) + ) + if hypo["alignment"] is not None and getarg( + "print_alignment", False + ): + logger.info( + "A\t{}".format( + " ".join( + [ + "{}-{}".format(src_idx, tgt_idx) + for src_idx, tgt_idx in hypo["alignment"] + ] + ) + ) + ) + return outputs + + def encode(self, sentence: str) -> torch.LongTensor: + sentence = self.tokenize(sentence) + sentence = self.apply_bpe(sentence) + return self.binarize(sentence) + + def decode(self, tokens: torch.LongTensor) -> str: + sentence = self.string(tokens) + sentence = self.remove_bpe(sentence) + return self.detokenize(sentence) + + def tokenize(self, sentence: str) -> str: + if self.tokenizer is not None: + sentence = self.tokenizer.encode(sentence) + return sentence + + def detokenize(self, sentence: str) -> str: + if self.tokenizer is not None: + sentence = self.tokenizer.decode(sentence) + return sentence + + def apply_bpe(self, sentence: str) -> str: + if self.bpe is not None: + sentence = self.bpe.encode(sentence) + return sentence + + def remove_bpe(self, sentence: str) -> str: + if self.bpe is not None: + sentence = self.bpe.decode(sentence) + return sentence + + def binarize(self, sentence: str) -> torch.LongTensor: + return self.src_dict.encode_line(sentence, add_if_not_exist=False).long() + + def string(self, tokens: torch.LongTensor) -> str: + return self.tgt_dict.string(tokens) + + def _build_batches( + self, tokens: List[List[int]], skip_invalid_size_inputs: bool + ) -> Iterator[Dict[str, Any]]: + lengths = torch.LongTensor([t.numel() for t in tokens]) + batch_iterator = self.task.get_batch_iterator( + dataset=self.task.build_dataset_for_inference(tokens, lengths), + max_tokens=self.cfg.dataset.max_tokens, + max_sentences=self.cfg.dataset.batch_size, + max_positions=self.max_positions, + ignore_invalid_inputs=skip_invalid_size_inputs, + disable_iterator_cache=True, + ).next_epoch_itr(shuffle=False) + return batch_iterator + + +class BPEHubInterface(object): + """PyTorch Hub interface for Byte-Pair Encoding (BPE).""" + + def __init__(self, bpe, **kwargs): + super().__init__() + args = argparse.Namespace(bpe=bpe, **kwargs) + self.bpe = encoders.build_bpe(args) + assert self.bpe is not None + + def encode(self, sentence: str) -> str: + return self.bpe.encode(sentence) + + def decode(self, sentence: str) -> str: + return self.bpe.decode(sentence) + + +class TokenizerHubInterface(object): + """PyTorch Hub interface for tokenization.""" + + def __init__(self, tokenizer, **kwargs): + super().__init__() + args = argparse.Namespace(tokenizer=tokenizer, **kwargs) + self.tokenizer = encoders.build_tokenizer(args) + assert self.tokenizer is not None + + def encode(self, sentence: str) -> str: + return self.tokenizer.encode(sentence) + + def decode(self, sentence: str) -> str: + return self.tokenizer.decode(sentence) diff --git a/PyTorch/NLP/new-Transformer/fairseq/incremental_decoding_utils.py b/PyTorch/NLP/new-Transformer/fairseq/incremental_decoding_utils.py new file mode 100644 index 00000000..b26e6cd0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/incremental_decoding_utils.py @@ -0,0 +1,51 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import uuid +from typing import Dict, Optional + +from torch import Tensor + + +class FairseqIncrementalState(object): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.init_incremental_state() + + def init_incremental_state(self): + self._incremental_state_id = str(uuid.uuid4()) + + def _get_full_incremental_state_key(self, key: str) -> str: + return "{}.{}".format(self._incremental_state_id, key) + + def get_incremental_state( + self, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]], + key: str, + ) -> Optional[Dict[str, Optional[Tensor]]]: + """Helper for getting incremental state for an nn.Module.""" + full_key = self._get_full_incremental_state_key(key) + if incremental_state is None or full_key not in incremental_state: + return None + return incremental_state[full_key] + + def set_incremental_state( + self, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]], + key: str, + value: Dict[str, Optional[Tensor]], + ) -> Optional[Dict[str, Dict[str, Optional[Tensor]]]]: + """Helper for setting incremental state for an nn.Module.""" + if incremental_state is not None: + full_key = self._get_full_incremental_state_key(key) + incremental_state[full_key] = value + return incremental_state + + +def with_incremental_state(cls): + cls.__bases__ = (FairseqIncrementalState,) + tuple( + b for b in cls.__bases__ if b != FairseqIncrementalState + ) + return cls diff --git a/PyTorch/NLP/new-Transformer/fairseq/iterative_refinement_generator.py b/PyTorch/NLP/new-Transformer/fairseq/iterative_refinement_generator.py new file mode 100644 index 00000000..4fb0946f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/iterative_refinement_generator.py @@ -0,0 +1,359 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections import namedtuple + +import numpy as np +import torch +from fairseq import utils + + +DecoderOut = namedtuple( + "IterativeRefinementDecoderOut", + ["output_tokens", "output_scores", "attn", "step", "max_step", "history"], +) + + +class IterativeRefinementGenerator(object): + def __init__( + self, + tgt_dict, + models=None, + eos_penalty=0.0, + max_iter=10, + max_ratio=2, + beam_size=1, + decoding_format=None, + retain_dropout=False, + adaptive=True, + retain_history=False, + reranking=False, + ): + """ + Generates translations based on iterative refinement. + + Args: + tgt_dict: target dictionary + eos_penalty: if > 0.0, it penalized early-stopping in decoding + max_iter: maximum number of refinement iterations + max_ratio: generate sequences of maximum length ax, where x is the source length + decoding_format: decoding mode in {'unigram', 'ensemble', 'vote', 'dp', 'bs'} + retain_dropout: retaining dropout in the inference + adaptive: decoding with early stop + """ + self.bos = tgt_dict.bos() + self.pad = tgt_dict.pad() + self.unk = tgt_dict.unk() + self.eos = tgt_dict.eos() + self.vocab_size = len(tgt_dict) + self.eos_penalty = eos_penalty + self.max_iter = max_iter + self.max_ratio = max_ratio + self.beam_size = beam_size + self.reranking = reranking + self.decoding_format = decoding_format + self.retain_dropout = retain_dropout + self.retain_history = retain_history + self.adaptive = adaptive + self.models = models + + def generate_batched_itr( + self, + data_itr, + maxlen_a=None, + maxlen_b=None, + cuda=False, + timer=None, + prefix_size=0, + ): + """Iterate over a batched dataset and yield individual translations. + + Args: + maxlen_a/b: generate sequences of maximum length ax + b, + where x is the source sentence length. + cuda: use GPU for generation + timer: StopwatchMeter for timing generations. + """ + + for sample in data_itr: + if "net_input" not in sample: + continue + if timer is not None: + timer.start() + with torch.no_grad(): + hypos = self.generate( + self.models, + sample, + prefix_tokens=sample["target"][:, :prefix_size] + if prefix_size > 0 + else None, + ) + if timer is not None: + timer.stop(sample["ntokens"]) + for i, id in enumerate(sample["id"]): + # remove padding + src = utils.strip_pad(sample["net_input"]["src_tokens"][i, :], self.pad) + ref = utils.strip_pad(sample["target"][i, :], self.pad) + yield id, src, ref, hypos[i] + + @torch.no_grad() + def generate(self, models, sample, prefix_tokens=None, constraints=None): + if constraints is not None: + raise NotImplementedError( + "Constrained decoding with the IterativeRefinementGenerator is not supported" + ) + + # TODO: iterative refinement generator does not support ensemble for now. + if not self.retain_dropout: + for model in models: + model.eval() + + model, reranker = models[0], None + if self.reranking: + assert len(models) > 1, "Assuming the last checkpoint is the reranker" + assert ( + self.beam_size > 1 + ), "Reranking requires multiple translation for each example" + + reranker = models[-1] + models = models[:-1] + + if len(models) > 1 and hasattr(model, "enable_ensemble"): + assert model.allow_ensemble, "{} does not support ensembling".format( + model.__class__.__name__ + ) + model.enable_ensemble(models) + + # TODO: better encoder inputs? + src_tokens = sample["net_input"]["src_tokens"] + src_lengths = sample["net_input"]["src_lengths"] + bsz, src_len = src_tokens.size() + + # initialize + encoder_out = model.forward_encoder([src_tokens, src_lengths]) + prev_decoder_out = model.initialize_output_tokens(encoder_out, src_tokens) + + if self.beam_size > 1: + assert ( + model.allow_length_beam + ), "{} does not support decoding with length beam.".format( + model.__class__.__name__ + ) + + # regenerate data based on length-beam + length_beam_order = ( + utils.new_arange(src_tokens, self.beam_size, bsz).t().reshape(-1) + ) + encoder_out = model.encoder.reorder_encoder_out( + encoder_out, length_beam_order + ) + prev_decoder_out = model.regenerate_length_beam( + prev_decoder_out, self.beam_size + ) + bsz = bsz * self.beam_size + + sent_idxs = torch.arange(bsz) + prev_output_tokens = prev_decoder_out.output_tokens.clone() + + if self.retain_history: + prev_decoder_out = prev_decoder_out._replace(history=[prev_output_tokens]) + + finalized = [[] for _ in range(bsz)] + + def is_a_loop(x, y, s, a): + b, l_x, l_y = x.size(0), x.size(1), y.size(1) + if l_x > l_y: + y = torch.cat([y, x.new_zeros(b, l_x - l_y).fill_(self.pad)], 1) + s = torch.cat([s, s.new_zeros(b, l_x - l_y)], 1) + if a is not None: + a = torch.cat([a, a.new_zeros(b, l_x - l_y, a.size(2))], 1) + elif l_x < l_y: + x = torch.cat([x, y.new_zeros(b, l_y - l_x).fill_(self.pad)], 1) + return (x == y).all(1), y, s, a + + def finalized_hypos(step, prev_out_token, prev_out_score, prev_out_attn): + cutoff = prev_out_token.ne(self.pad) + tokens = prev_out_token[cutoff] + if prev_out_score is None: + scores, score = None, None + else: + scores = prev_out_score[cutoff] + score = scores.mean() + + if prev_out_attn is None: + hypo_attn, alignment = None, None + else: + hypo_attn = prev_out_attn[cutoff] + alignment = hypo_attn.max(dim=1)[1] + return { + "steps": step, + "tokens": tokens, + "positional_scores": scores, + "score": score, + "hypo_attn": hypo_attn, + "alignment": alignment, + } + + for step in range(self.max_iter + 1): + + decoder_options = { + "eos_penalty": self.eos_penalty, + "max_ratio": self.max_ratio, + "decoding_format": self.decoding_format, + } + prev_decoder_out = prev_decoder_out._replace( + step=step, + max_step=self.max_iter + 1, + ) + + decoder_out = model.forward_decoder( + prev_decoder_out, encoder_out, **decoder_options + ) + + if self.adaptive: + # terminate if there is a loop + terminated, out_tokens, out_scores, out_attn = is_a_loop( + prev_output_tokens, + decoder_out.output_tokens, + decoder_out.output_scores, + decoder_out.attn, + ) + decoder_out = decoder_out._replace( + output_tokens=out_tokens, + output_scores=out_scores, + attn=out_attn, + ) + + else: + terminated = decoder_out.output_tokens.new_zeros( + decoder_out.output_tokens.size(0) + ).bool() + + if step == self.max_iter: # reach last iteration, terminate + terminated.fill_(1) + + # collect finalized sentences + finalized_idxs = sent_idxs[terminated] + finalized_tokens = decoder_out.output_tokens[terminated] + finalized_scores = decoder_out.output_scores[terminated] + finalized_attn = ( + None + if (decoder_out.attn is None or decoder_out.attn.size(0) == 0) + else decoder_out.attn[terminated] + ) + + if self.retain_history: + finalized_history_tokens = [h[terminated] for h in decoder_out.history] + + for i in range(finalized_idxs.size(0)): + finalized[finalized_idxs[i]] = [ + finalized_hypos( + step, + finalized_tokens[i], + finalized_scores[i], + None if finalized_attn is None else finalized_attn[i], + ) + ] + + if self.retain_history: + finalized[finalized_idxs[i]][0]["history"] = [] + for j in range(len(finalized_history_tokens)): + finalized[finalized_idxs[i]][0]["history"].append( + finalized_hypos( + step, finalized_history_tokens[j][i], None, None + ) + ) + + # check if all terminated + if terminated.sum() == terminated.size(0): + break + + # for next step + not_terminated = ~terminated + prev_decoder_out = decoder_out._replace( + output_tokens=decoder_out.output_tokens[not_terminated], + output_scores=decoder_out.output_scores[not_terminated], + attn=decoder_out.attn[not_terminated] + if (decoder_out.attn is not None and decoder_out.attn.size(0) > 0) + else None, + history=[h[not_terminated] for h in decoder_out.history] + if decoder_out.history is not None + else None, + ) + encoder_out = model.encoder.reorder_encoder_out( + encoder_out, not_terminated.nonzero(as_tuple=False).squeeze() + ) + sent_idxs = sent_idxs[not_terminated] + prev_output_tokens = prev_decoder_out.output_tokens.clone() + + if self.beam_size > 1: + if reranker is not None: + finalized = self.rerank( + reranker, finalized, [src_tokens, src_lengths], self.beam_size + ) + + # aggregate information from length beam + finalized = [ + finalized[ + np.argmax( + [ + finalized[self.beam_size * i + j][0]["score"] + for j in range(self.beam_size) + ] + ) + + self.beam_size * i + ] + for i in range(len(finalized) // self.beam_size) + ] + + return finalized + + def rerank(self, reranker, finalized, encoder_input, beam_size): + def rebuild_batch(finalized): + finalized_tokens = [f[0]["tokens"] for f in finalized] + finalized_maxlen = max(f.size(0) for f in finalized_tokens) + final_output_tokens = ( + finalized_tokens[0] + .new_zeros(len(finalized_tokens), finalized_maxlen) + .fill_(self.pad) + ) + for i, f in enumerate(finalized_tokens): + final_output_tokens[i, : f.size(0)] = f + return final_output_tokens + + final_output_tokens = rebuild_batch(finalized) + final_output_tokens[ + :, 0 + ] = self.eos # autoregressive model assumes starting with EOS + + reranker_encoder_out = reranker.encoder(*encoder_input) + length_beam_order = ( + utils.new_arange( + final_output_tokens, beam_size, reranker_encoder_out.encoder_out.size(1) + ) + .t() + .reshape(-1) + ) + reranker_encoder_out = reranker.encoder.reorder_encoder_out( + reranker_encoder_out, length_beam_order + ) + reranking_scores = reranker.get_normalized_probs( + reranker.decoder(final_output_tokens[:, :-1], reranker_encoder_out), + True, + None, + ) + reranking_scores = reranking_scores.gather(2, final_output_tokens[:, 1:, None]) + reranking_masks = final_output_tokens[:, 1:].ne(self.pad) + reranking_scores = ( + reranking_scores[:, :, 0].masked_fill_(~reranking_masks, 0).sum(1) + ) + reranking_scores = reranking_scores / reranking_masks.sum(1).type_as( + reranking_scores + ) + + for i in range(len(finalized)): + finalized[i][0]["score"] = reranking_scores[i] + + return finalized diff --git a/PyTorch/NLP/Transformer/.gitmodules b/PyTorch/NLP/new-Transformer/fairseq/logging/__init__.py similarity index 100% rename from PyTorch/NLP/Transformer/.gitmodules rename to PyTorch/NLP/new-Transformer/fairseq/logging/__init__.py diff --git a/PyTorch/NLP/new-Transformer/fairseq/logging/meters.py b/PyTorch/NLP/new-Transformer/fairseq/logging/meters.py new file mode 100644 index 00000000..d5f7c775 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/logging/meters.py @@ -0,0 +1,321 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import bisect +import time +from collections import OrderedDict +from typing import Dict, Optional + +try: + import torch + + def type_as(a, b): + if torch.is_tensor(a) and torch.is_tensor(b): + return a.to(b) + else: + return a + +except ImportError: + torch = None + + def type_as(a, b): + return a + + +try: + import numpy as np +except ImportError: + np = None + + +class Meter(object): + """Base class for Meters.""" + + def __init__(self): + pass + + def state_dict(self): + return {} + + def load_state_dict(self, state_dict): + pass + + def reset(self): + raise NotImplementedError + + @property + def smoothed_value(self) -> float: + """Smoothed value used for logging.""" + raise NotImplementedError + + +def safe_round(number, ndigits): + if hasattr(number, "__round__"): + return round(number, ndigits) + elif torch is not None and torch.is_tensor(number) and number.numel() == 1: + return safe_round(number.item(), ndigits) + elif np is not None and np.ndim(number) == 0 and hasattr(number, "item"): + return safe_round(number.item(), ndigits) + else: + return number + + +class AverageMeter(Meter): + """Computes and stores the average and current value""" + + def __init__(self, round: Optional[int] = None): + self.round = round + self.reset() + + def reset(self): + self.val = None # most recent update + self.sum = 0 # sum from all updates + self.count = 0 # total n from all updates + + def update(self, val, n=1): + if val is not None: + self.val = val + if n > 0: + self.sum = type_as(self.sum, val) + (val * n) + self.count = type_as(self.count, n) + n + + def state_dict(self): + return { + "val": self.val, + "sum": self.sum, + "count": self.count, + "round": self.round, + } + + def load_state_dict(self, state_dict): + self.val = state_dict["val"] + self.sum = state_dict["sum"] + self.count = state_dict["count"] + self.round = state_dict.get("round", None) + + @property + def avg(self): + return self.sum / self.count if self.count > 0 else self.val + + @property + def smoothed_value(self) -> float: + val = self.avg + if self.round is not None and val is not None: + val = safe_round(val, self.round) + return val + + +class SumMeter(Meter): + """Computes and stores the sum""" + + def __init__(self, round: Optional[int] = None): + self.round = round + self.reset() + + def reset(self): + self.sum = 0 # sum from all updates + + def update(self, val): + if val is not None: + self.sum = type_as(self.sum, val) + val + + def state_dict(self): + return { + "sum": self.sum, + "round": self.round, + } + + def load_state_dict(self, state_dict): + self.sum = state_dict["sum"] + self.round = state_dict.get("round", None) + + @property + def smoothed_value(self) -> float: + val = self.sum + if self.round is not None and val is not None: + val = safe_round(val, self.round) + return val + + +class TimeMeter(Meter): + """Computes the average occurrence of some event per second""" + + def __init__( + self, + init: int = 0, + n: int = 0, + round: Optional[int] = None, + ): + self.round = round + self.reset(init, n) + + def reset(self, init=0, n=0): + self.init = init + self.start = time.perf_counter() + self.n = n + self.i = 0 + + def update(self, val=1): + self.n = type_as(self.n, val) + val + self.i += 1 + + def state_dict(self): + return { + "init": self.elapsed_time, + "n": self.n, + "round": self.round, + } + + def load_state_dict(self, state_dict): + if "start" in state_dict: + # backwards compatibility for old state_dicts + self.reset(init=state_dict["init"]) + else: + self.reset(init=state_dict["init"], n=state_dict["n"]) + self.round = state_dict.get("round", None) + + @property + def avg(self): + return self.n / self.elapsed_time + + @property + def elapsed_time(self): + return self.init + (time.perf_counter() - self.start) + + @property + def smoothed_value(self) -> float: + val = self.avg + if self.round is not None and val is not None: + val = safe_round(val, self.round) + return val + + +class StopwatchMeter(Meter): + """Computes the sum/avg duration of some event in seconds""" + + def __init__(self, round: Optional[int] = None): + self.round = round + self.sum = 0 + self.n = 0 + self.start_time = None + + def start(self): + self.start_time = time.perf_counter() + + def stop(self, n=1, prehook=None): + if self.start_time is not None: + if prehook is not None: + prehook() + delta = time.perf_counter() - self.start_time + self.sum = self.sum + delta + self.n = type_as(self.n, n) + n + + def reset(self): + self.sum = 0 # cumulative time during which stopwatch was active + self.n = 0 # total n across all start/stop + self.start() + + def state_dict(self): + return { + "sum": self.sum, + "n": self.n, + "round": self.round, + } + + def load_state_dict(self, state_dict): + self.sum = state_dict["sum"] + self.n = state_dict["n"] + self.start_time = None + self.round = state_dict.get("round", None) + + @property + def avg(self): + return self.sum / self.n if self.n > 0 else self.sum + + @property + def elapsed_time(self): + if self.start_time is None: + return 0.0 + return time.perf_counter() - self.start_time + + @property + def smoothed_value(self) -> float: + val = self.avg if self.sum > 0 else self.elapsed_time + if self.round is not None and val is not None: + val = safe_round(val, self.round) + return val + + +class MetersDict(OrderedDict): + """A sorted dictionary of :class:`Meters`. + + Meters are sorted according to a priority that is given when the + meter is first added to the dictionary. + """ + + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self.priorities = [] + + def __setitem__(self, key, value): + assert key not in self, "MetersDict doesn't support reassignment" + priority, value = value + bisect.insort(self.priorities, (priority, len(self.priorities), key)) + super().__setitem__(key, value) + for _, _, key in self.priorities: # reorder dict to match priorities + self.move_to_end(key) + + def add_meter(self, key, meter, priority): + self.__setitem__(key, (priority, meter)) + + def state_dict(self): + return [ + (pri, key, self[key].__class__.__name__, self[key].state_dict()) + for pri, _, key in self.priorities + # can't serialize DerivedMeter instances + if not isinstance(self[key], MetersDict._DerivedMeter) + ] + + def load_state_dict(self, state_dict): + self.clear() + self.priorities.clear() + for pri, key, meter_cls, meter_state in state_dict: + meter = globals()[meter_cls]() + meter.load_state_dict(meter_state) + self.add_meter(key, meter, pri) + + def get_smoothed_value(self, key: str) -> float: + """Get a single smoothed value.""" + meter = self[key] + if isinstance(meter, MetersDict._DerivedMeter): + return meter.fn(self) + else: + return meter.smoothed_value + + def get_smoothed_values(self) -> Dict[str, float]: + """Get all smoothed values.""" + return OrderedDict( + [ + (key, self.get_smoothed_value(key)) + for key in self.keys() + if not key.startswith("_") + ] + ) + + def reset(self): + """Reset Meter instances.""" + for meter in self.values(): + if isinstance(meter, MetersDict._DerivedMeter): + continue + meter.reset() + + class _DerivedMeter(Meter): + """A Meter whose values are derived from other Meters.""" + + def __init__(self, fn): + self.fn = fn + + def reset(self): + pass diff --git a/PyTorch/NLP/new-Transformer/fairseq/logging/metrics.py b/PyTorch/NLP/new-Transformer/fairseq/logging/metrics.py new file mode 100644 index 00000000..892b0ea4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/logging/metrics.py @@ -0,0 +1,316 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +A standalone module for aggregating metrics. + +Metrics can be logged from anywhere using the `log_*` functions defined +in this module. The logged values will be aggregated dynamically based +on the aggregation context in which the logging occurs. See the +:func:`aggregate` context manager for more details. +""" + +import contextlib +import uuid +from collections import defaultdict +from typing import Callable, List, Optional + +from .meters import * + + +# Aggregation contexts are considered "active" when inside the scope +# created by the :func:`aggregate` context manager. +_aggregators = OrderedDict() +_active_aggregators = OrderedDict() +_active_aggregators_cnt = defaultdict(lambda: 0) + + +def reset() -> None: + """Reset all metrics aggregators.""" + _aggregators.clear() + _active_aggregators.clear() + _active_aggregators_cnt.clear() + + # The "default" aggregator observes all logged values. + _aggregators["default"] = MetersDict() + _active_aggregators["default"] = _aggregators["default"] + _active_aggregators_cnt["default"] = 1 + + +reset() + + +@contextlib.contextmanager +def aggregate(name: Optional[str] = None, new_root: bool = False): + """Context manager to aggregate metrics under a given name. + + Aggregations can be nested. If *new_root* is ``False``, then logged + metrics will be recorded along the entire stack of nested + aggregators, including a global "default" aggregator. If *new_root* + is ``True``, then this aggregator will be the root of a new + aggregation stack, thus bypassing any parent aggregators. + + Note that aggregation contexts are uniquely identified by their + *name* (e.g., train, valid). Creating a context with an existing + name will reuse the corresponding :class:`MetersDict` instance. + If no name is given, then a temporary aggregator will be created. + + Usage:: + + with metrics.aggregate("train"): + for step, batch in enumerate(epoch): + with metrics.aggregate("train_inner") as agg: + metrics.log_scalar("loss", get_loss(batch)) + if step % log_interval == 0: + print(agg.get_smoothed_value("loss")) + agg.reset() + print(metrics.get_smoothed_values("train")["loss"]) + + Args: + name (str): name of the aggregation. Defaults to a + random/temporary name if not given explicitly. + new_root (bool): make this aggregation the root of a new + aggregation stack. + """ + if name is None: + # generate a temporary name + name = str(uuid.uuid4()) + assert name not in _aggregators + agg = MetersDict() + else: + assert name != "default" + agg = _aggregators.setdefault(name, MetersDict()) + + if new_root: + backup_aggregators = _active_aggregators.copy() + _active_aggregators.clear() + backup_aggregators_cnt = _active_aggregators_cnt.copy() + _active_aggregators_cnt.clear() + + _active_aggregators[name] = agg + _active_aggregators_cnt[name] += 1 + + yield agg + + _active_aggregators_cnt[name] -= 1 + if _active_aggregators_cnt[name] == 0 and name in _active_aggregators: + del _active_aggregators[name] + + if new_root: + _active_aggregators.clear() + _active_aggregators.update(backup_aggregators) + _active_aggregators_cnt.clear() + _active_aggregators_cnt.update(backup_aggregators_cnt) + + +def get_active_aggregators() -> List[MetersDict]: + return list(_active_aggregators.values()) + + +def log_scalar( + key: str, + value: float, + weight: float = 1, + priority: int = 10, + round: Optional[int] = None, +): + """Log a scalar value. + + Args: + key (str): name of the field to log + value (float): value to log + weight (float): weight that this value contributes to the average. + A weight of 0 will always log the latest value. + priority (int): smaller values are logged earlier in the output + round (Optional[int]): number of digits to round to when displaying + """ + for agg in get_active_aggregators(): + if key not in agg: + agg.add_meter(key, AverageMeter(round=round), priority) + agg[key].update(value, weight) + + +def log_scalar_sum( + key: str, + value: float, + priority: int = 10, + round: Optional[int] = None, +): + """Log a scalar value that is summed for reporting. + + Args: + key (str): name of the field to log + value (float): value to log + priority (int): smaller values are logged earlier in the output + round (Optional[int]): number of digits to round to when displaying + """ + for agg in get_active_aggregators(): + if key not in agg: + agg.add_meter(key, SumMeter(round=round), priority) + agg[key].update(value) + + +def log_derived(key: str, fn: Callable[[MetersDict], float], priority: int = 20): + """Log a scalar value derived from other meters. + + Args: + key (str): name of the field to log + fn (Callable[[MetersDict], float]): function that takes a single + argument *meters* and returns the derived value + priority (int): smaller values are logged earlier in the output + """ + for agg in get_active_aggregators(): + if key not in agg: + agg.add_meter(key, MetersDict._DerivedMeter(fn), priority) + + +def log_speed( + key: str, + value: float, + priority: int = 30, + round: Optional[int] = None, +): + """Log the rate of some quantity per second. + + Args: + key (str): name of the field to log + value (float): value to log + priority (int): smaller values are logged earlier in the output + round (Optional[int]): number of digits to round to when displaying + """ + for agg in get_active_aggregators(): + if key not in agg: + agg.add_meter(key, TimeMeter(round=round), priority) + agg[key].reset() # reset meter on the first call + else: + agg[key].update(value) + + +def log_start_time(key: str, priority: int = 40, round: Optional[int] = None): + """Log the duration of some event in seconds. + + The duration will be computed once :func:`log_stop_time` is called. + + Args: + key (str): name of the field to log + priority (int): smaller values are logged earlier in the output + round (Optional[int]): number of digits to round to when displaying + """ + for agg in get_active_aggregators(): + if key not in agg: + agg.add_meter(key, StopwatchMeter(round=round), priority) + agg[key].start() + + +def log_stop_time(key: str, weight: float = 0.0, prehook=None): + """Log the duration of some event in seconds. + + The duration will be computed since :func:`log_start_time` was called. + Set weight > 0 to report the average time instead of the sum. + + Args: + key (str): name of the field to log + weight (float): weight that this time contributes to the average + prehook (function, no arguments): will be called before the timer + is stopped. For example, use prehook=torch.cuda.synchronize to + make sure all gpu operations are done before timer is stopped. + """ + for agg in get_active_aggregators(): + if key in agg: + agg[key].stop(weight, prehook) + + +def log_custom( + new_meter_fn: Callable[[], Meter], + key: str, + *args, + priority: int = 50, + **kwargs, +): + """Log using a custom Meter. + + Any extra *args* or *kwargs* will be passed through to the Meter's + *update* method. + + Args: + new_meter_fn (Callable[[], Meter]): function that returns a new + Meter instance + key (str): name of the field to log + priority (int): smaller values are logged earlier in the output + """ + for agg in get_active_aggregators(): + if key not in agg: + agg.add_meter(key, new_meter_fn(), priority) + agg[key].update(*args, **kwargs) + + +def reset_meter(name: str, key: str) -> None: + """Reset Meter instance aggregated under a given *name* and *key*.""" + meter = get_meter(name, key) + if meter is not None: + meter.reset() + + +def reset_meters(name: str) -> None: + """Reset Meter instances aggregated under a given *name*.""" + meters = get_meters(name) + if meters is not None: + meters.reset() + + +def get_meter(name: str, key: str) -> Meter: + """Get a single Meter instance aggregated under *name* and *key*. + + Returns: + Meter or None if no metrics have been logged under *name* and *key*. + """ + if name not in _aggregators: + return None + return _aggregators[name].get(key, None) + + +def get_meters(name: str) -> MetersDict: + """Get Meter instances aggregated under a given *name*. + + Returns: + MetersDict or None if no metrics have been logged under *name*. + """ + return _aggregators.get(name, None) + + +def get_smoothed_value(name: str, key: str) -> float: + """Get a single smoothed value. + + Raises: + KeyError: if no metrics have been logged under *name* and *key*. + """ + return _aggregators[name].get_smoothed_value(key) + + +def get_smoothed_values(name: str) -> Dict[str, float]: + """Get smoothed values aggregated under a given *name*. + + Raises: + KeyError: if no metrics have been logged under *name*. + """ + return _aggregators[name].get_smoothed_values() + + +def state_dict(): + return OrderedDict([(name, agg.state_dict()) for name, agg in _aggregators.items()]) + + +def load_state_dict(state_dict): + for name, agg_state in state_dict.items(): + _aggregators[name] = MetersDict() + _aggregators[name].load_state_dict(agg_state) + + +def xla_metrics_report(): + try: + import torch_xla.debug.metrics as met + + print(met.metrics_report()) + except ImportError: + return diff --git a/PyTorch/NLP/new-Transformer/fairseq/logging/progress_bar.py b/PyTorch/NLP/new-Transformer/fairseq/logging/progress_bar.py new file mode 100644 index 00000000..4c64b61b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/logging/progress_bar.py @@ -0,0 +1,582 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +""" +Wrapper around various loggers and progress bars (e.g., tqdm). +""" + +import atexit +import json +import logging +import os +import sys +from collections import OrderedDict +from contextlib import contextmanager +from numbers import Number +from typing import Optional + +import torch + +from .meters import AverageMeter, StopwatchMeter, TimeMeter + +logger = logging.getLogger(__name__) + + +def progress_bar( + iterator, + log_format: Optional[str] = None, + log_interval: int = 100, + log_file: Optional[str] = None, + epoch: Optional[int] = None, + prefix: Optional[str] = None, + aim_repo: Optional[str] = None, + aim_run_hash: Optional[str] = None, + aim_param_checkpoint_dir: Optional[str] = None, + tensorboard_logdir: Optional[str] = None, + default_log_format: str = "tqdm", + wandb_project: Optional[str] = None, + wandb_run_name: Optional[str] = None, + azureml_logging: Optional[bool] = False, +): + if log_format is None: + log_format = default_log_format + if log_file is not None: + handler = logging.FileHandler(filename=log_file) + logger.addHandler(handler) + + if log_format == "tqdm" and not sys.stderr.isatty(): + log_format = "simple" + + if log_format == "json": + bar = JsonProgressBar(iterator, epoch, prefix, log_interval) + elif log_format == "none": + bar = NoopProgressBar(iterator, epoch, prefix) + elif log_format == "simple": + bar = SimpleProgressBar(iterator, epoch, prefix, log_interval) + elif log_format == "tqdm": + bar = TqdmProgressBar(iterator, epoch, prefix) + else: + raise ValueError("Unknown log format: {}".format(log_format)) + + if aim_repo: + bar = AimProgressBarWrapper( + bar, + aim_repo=aim_repo, + aim_run_hash=aim_run_hash, + aim_param_checkpoint_dir=aim_param_checkpoint_dir, + ) + + if tensorboard_logdir: + try: + # [FB only] custom wrapper for TensorBoard + import palaas # noqa + + from .fb_tbmf_wrapper import FbTbmfWrapper + + bar = FbTbmfWrapper(bar, log_interval) + except ImportError: + bar = TensorboardProgressBarWrapper(bar, tensorboard_logdir) + + if wandb_project: + bar = WandBProgressBarWrapper(bar, wandb_project, run_name=wandb_run_name) + + if azureml_logging: + bar = AzureMLProgressBarWrapper(bar) + + return bar + + +def build_progress_bar( + args, + iterator, + epoch: Optional[int] = None, + prefix: Optional[str] = None, + default: str = "tqdm", + no_progress_bar: str = "none", +): + """Legacy wrapper that takes an argparse.Namespace.""" + if getattr(args, "no_progress_bar", False): + default = no_progress_bar + if getattr(args, "distributed_rank", 0) == 0: + tensorboard_logdir = getattr(args, "tensorboard_logdir", None) + else: + tensorboard_logdir = None + return progress_bar( + iterator, + log_format=args.log_format, + log_interval=args.log_interval, + epoch=epoch, + prefix=prefix, + tensorboard_logdir=tensorboard_logdir, + default_log_format=default, + ) + + +def format_stat(stat): + if isinstance(stat, Number): + stat = "{:g}".format(stat) + elif isinstance(stat, AverageMeter): + stat = "{:.3f}".format(stat.avg) + elif isinstance(stat, TimeMeter): + stat = "{:g}".format(round(stat.avg)) + elif isinstance(stat, StopwatchMeter): + stat = "{:g}".format(round(stat.sum)) + elif torch.is_tensor(stat): + stat = stat.tolist() + return stat + + +class BaseProgressBar(object): + """Abstract class for progress bars.""" + + def __init__(self, iterable, epoch=None, prefix=None): + self.iterable = iterable + self.n = getattr(iterable, "n", 0) + self.epoch = epoch + self.prefix = "" + if epoch is not None: + self.prefix += "epoch {:03d}".format(epoch) + if prefix is not None: + self.prefix += (" | " if self.prefix != "" else "") + prefix + + def __len__(self): + return len(self.iterable) + + def __enter__(self): + return self + + def __exit__(self, *exc): + return False + + def __iter__(self): + raise NotImplementedError + + def log(self, stats, tag=None, step=None): + """Log intermediate stats according to log_interval.""" + raise NotImplementedError + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats.""" + raise NotImplementedError + + def update_config(self, config): + """Log latest configuration.""" + pass + + def _str_commas(self, stats): + return ", ".join(key + "=" + stats[key].strip() for key in stats.keys()) + + def _str_pipes(self, stats): + return " | ".join(key + " " + stats[key].strip() for key in stats.keys()) + + def _format_stats(self, stats): + postfix = OrderedDict(stats) + # Preprocess stats according to datatype + for key in postfix.keys(): + postfix[key] = str(format_stat(postfix[key])) + return postfix + + +@contextmanager +def rename_logger(logger, new_name): + old_name = logger.name + if new_name is not None: + logger.name = new_name + yield logger + logger.name = old_name + + +class JsonProgressBar(BaseProgressBar): + """Log output in JSON format.""" + + def __init__(self, iterable, epoch=None, prefix=None, log_interval=1000): + super().__init__(iterable, epoch, prefix) + self.log_interval = log_interval + self.i = None + self.size = None + + def __iter__(self): + self.size = len(self.iterable) + for i, obj in enumerate(self.iterable, start=self.n): + self.i = i + yield obj + + def log(self, stats, tag=None, step=None): + """Log intermediate stats according to log_interval.""" + step = step or self.i or 0 + if step > 0 and self.log_interval is not None and step % self.log_interval == 0: + update = ( + self.epoch - 1 + (self.i + 1) / float(self.size) + if self.epoch is not None + else None + ) + stats = self._format_stats(stats, epoch=self.epoch, update=update) + with rename_logger(logger, tag): + logger.info(json.dumps(stats)) + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats.""" + self.stats = stats + if tag is not None: + self.stats = OrderedDict( + [(tag + "_" + k, v) for k, v in self.stats.items()] + ) + stats = self._format_stats(self.stats, epoch=self.epoch) + with rename_logger(logger, tag): + logger.info(json.dumps(stats)) + + def _format_stats(self, stats, epoch=None, update=None): + postfix = OrderedDict() + if epoch is not None: + postfix["epoch"] = epoch + if update is not None: + postfix["update"] = round(update, 3) + # Preprocess stats according to datatype + for key in stats.keys(): + postfix[key] = format_stat(stats[key]) + return postfix + + +class NoopProgressBar(BaseProgressBar): + """No logging.""" + + def __init__(self, iterable, epoch=None, prefix=None): + super().__init__(iterable, epoch, prefix) + + def __iter__(self): + for obj in self.iterable: + yield obj + + def log(self, stats, tag=None, step=None): + """Log intermediate stats according to log_interval.""" + pass + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats.""" + pass + + +class SimpleProgressBar(BaseProgressBar): + """A minimal logger for non-TTY environments.""" + + def __init__(self, iterable, epoch=None, prefix=None, log_interval=1000): + super().__init__(iterable, epoch, prefix) + self.log_interval = log_interval + self.i = None + self.size = None + + def __iter__(self): + self.size = len(self.iterable) + for i, obj in enumerate(self.iterable, start=self.n): + self.i = i + yield obj + + def log(self, stats, tag=None, step=None): + """Log intermediate stats according to log_interval.""" + step = step or self.i or 0 + if step > 0 and self.log_interval is not None and step % self.log_interval == 0: + stats = self._format_stats(stats) + postfix = self._str_commas(stats) + with rename_logger(logger, tag): + logger.info( + "{}: {:5d} / {:d} {}".format( + self.prefix, self.i + 1, self.size, postfix + ) + ) + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats.""" + postfix = self._str_pipes(self._format_stats(stats)) + with rename_logger(logger, tag): + logger.info("{} | {}".format(self.prefix, postfix)) + + +class TqdmProgressBar(BaseProgressBar): + """Log to tqdm.""" + + def __init__(self, iterable, epoch=None, prefix=None): + super().__init__(iterable, epoch, prefix) + from tqdm import tqdm + + self.tqdm = tqdm( + iterable, + self.prefix, + leave=False, + disable=(logger.getEffectiveLevel() > logging.INFO), + ) + + def __iter__(self): + return iter(self.tqdm) + + def log(self, stats, tag=None, step=None): + """Log intermediate stats according to log_interval.""" + self.tqdm.set_postfix(self._format_stats(stats), refresh=False) + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats.""" + postfix = self._str_pipes(self._format_stats(stats)) + with rename_logger(logger, tag): + logger.info("{} | {}".format(self.prefix, postfix)) + + +try: + import functools + + from aim import Repo as AimRepo + + @functools.lru_cache() + def get_aim_run(repo, run_hash): + from aim import Run + + return Run(run_hash=run_hash, repo=repo) + +except ImportError: + get_aim_run = None + AimRepo = None + + +class AimProgressBarWrapper(BaseProgressBar): + """Log to Aim.""" + + def __init__(self, wrapped_bar, aim_repo, aim_run_hash, aim_param_checkpoint_dir): + self.wrapped_bar = wrapped_bar + + if get_aim_run is None: + self.run = None + logger.warning("Aim not found, please install with: pip install aim") + else: + logger.info(f"Storing logs at Aim repo: {aim_repo}") + + if not aim_run_hash: + # Find run based on save_dir parameter + query = f"run.checkpoint.save_dir == '{aim_param_checkpoint_dir}'" + try: + runs_generator = AimRepo(aim_repo).query_runs(query) + run = next(runs_generator.iter_runs()) + aim_run_hash = run.run.hash + except Exception: + pass + + if aim_run_hash: + logger.info(f"Appending to run: {aim_run_hash}") + + self.run = get_aim_run(aim_repo, aim_run_hash) + + def __iter__(self): + return iter(self.wrapped_bar) + + def log(self, stats, tag=None, step=None): + """Log intermediate stats to Aim.""" + self._log_to_aim(stats, tag, step) + self.wrapped_bar.log(stats, tag=tag, step=step) + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats.""" + self._log_to_aim(stats, tag, step) + self.wrapped_bar.print(stats, tag=tag, step=step) + + def update_config(self, config): + """Log latest configuration.""" + if self.run is not None: + for key in config: + self.run.set(key, config[key], strict=False) + self.wrapped_bar.update_config(config) + + def _log_to_aim(self, stats, tag=None, step=None): + if self.run is None: + return + + if step is None: + step = stats["num_updates"] + + if "train" in tag: + context = {"tag": tag, "subset": "train"} + elif "val" in tag: + context = {"tag": tag, "subset": "val"} + else: + context = {"tag": tag} + + for key in stats.keys() - {"num_updates"}: + self.run.track(stats[key], name=key, step=step, context=context) + + +try: + _tensorboard_writers = {} + from torch.utils.tensorboard import SummaryWriter +except ImportError: + try: + from tensorboardX import SummaryWriter + except ImportError: + SummaryWriter = None + + +def _close_writers(): + for w in _tensorboard_writers.values(): + w.close() + + +atexit.register(_close_writers) + + +class TensorboardProgressBarWrapper(BaseProgressBar): + """Log to tensorboard.""" + + def __init__(self, wrapped_bar, tensorboard_logdir): + self.wrapped_bar = wrapped_bar + self.tensorboard_logdir = tensorboard_logdir + + if SummaryWriter is None: + logger.warning( + "tensorboard not found, please install with: pip install tensorboard" + ) + + def _writer(self, key): + if SummaryWriter is None: + return None + _writers = _tensorboard_writers + if key not in _writers: + _writers[key] = SummaryWriter(os.path.join(self.tensorboard_logdir, key)) + _writers[key].add_text("sys.argv", " ".join(sys.argv)) + return _writers[key] + + def __iter__(self): + return iter(self.wrapped_bar) + + def log(self, stats, tag=None, step=None): + """Log intermediate stats to tensorboard.""" + self._log_to_tensorboard(stats, tag, step) + self.wrapped_bar.log(stats, tag=tag, step=step) + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats.""" + self._log_to_tensorboard(stats, tag, step) + self.wrapped_bar.print(stats, tag=tag, step=step) + + def update_config(self, config): + """Log latest configuration.""" + # TODO add hparams to Tensorboard + self.wrapped_bar.update_config(config) + + def _log_to_tensorboard(self, stats, tag=None, step=None): + writer = self._writer(tag or "") + if writer is None: + return + if step is None: + step = stats["num_updates"] + for key in stats.keys() - {"num_updates"}: + if isinstance(stats[key], AverageMeter): + writer.add_scalar(key, stats[key].val, step) + elif isinstance(stats[key], Number): + writer.add_scalar(key, stats[key], step) + elif torch.is_tensor(stats[key]) and stats[key].numel() == 1: + writer.add_scalar(key, stats[key].item(), step) + writer.flush() + + +try: + import wandb +except ImportError: + wandb = None + + +class WandBProgressBarWrapper(BaseProgressBar): + """Log to Weights & Biases.""" + + def __init__(self, wrapped_bar, wandb_project, run_name=None): + self.wrapped_bar = wrapped_bar + if wandb is None: + logger.warning("wandb not found, pip install wandb") + return + + # reinit=False to ensure if wandb.init() is called multiple times + # within one process it still references the same run + wandb.init(project=wandb_project, reinit=False, name=run_name) + + def __iter__(self): + return iter(self.wrapped_bar) + + def log(self, stats, tag=None, step=None): + """Log intermediate stats to tensorboard.""" + self._log_to_wandb(stats, tag, step) + self.wrapped_bar.log(stats, tag=tag, step=step) + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats.""" + self._log_to_wandb(stats, tag, step) + self.wrapped_bar.print(stats, tag=tag, step=step) + + def update_config(self, config): + """Log latest configuration.""" + if wandb is not None: + wandb.config.update(config) + self.wrapped_bar.update_config(config) + + def _log_to_wandb(self, stats, tag=None, step=None): + if wandb is None: + return + if step is None: + step = stats["num_updates"] + + prefix = "" if tag is None else tag + "/" + + for key in stats.keys() - {"num_updates"}: + if isinstance(stats[key], AverageMeter): + wandb.log({prefix + key: stats[key].val}, step=step) + elif isinstance(stats[key], Number): + wandb.log({prefix + key: stats[key]}, step=step) + + +try: + from azureml.core import Run +except ImportError: + Run = None + + +class AzureMLProgressBarWrapper(BaseProgressBar): + """Log to Azure ML""" + + def __init__(self, wrapped_bar): + self.wrapped_bar = wrapped_bar + if Run is None: + logger.warning("azureml.core not found, pip install azureml-core") + return + self.run = Run.get_context() + + def __exit__(self, *exc): + if Run is not None: + self.run.complete() + return False + + def __iter__(self): + return iter(self.wrapped_bar) + + def log(self, stats, tag=None, step=None): + """Log intermediate stats to AzureML""" + self._log_to_azureml(stats, tag, step) + self.wrapped_bar.log(stats, tag=tag, step=step) + + def print(self, stats, tag=None, step=None): + """Print end-of-epoch stats""" + self._log_to_azureml(stats, tag, step) + self.wrapped_bar.print(stats, tag=tag, step=step) + + def update_config(self, config): + """Log latest configuration.""" + self.wrapped_bar.update_config(config) + + def _log_to_azureml(self, stats, tag=None, step=None): + if Run is None: + return + if step is None: + step = stats["num_updates"] + + prefix = "" if tag is None else tag + "/" + + for key in stats.keys() - {"num_updates"}: + name = prefix + key + if isinstance(stats[key], AverageMeter): + self.run.log_row(name=name, **{"step": step, key: stats[key].val}) + elif isinstance(stats[key], Number): + self.run.log_row(name=name, **{"step": step, key: stats[key]}) diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/__init__.py new file mode 100644 index 00000000..69f21684 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/__init__.py @@ -0,0 +1,6 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from . import criterions, models, modules # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/criterions/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/criterions/__init__.py new file mode 100644 index 00000000..5fae7bd4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/criterions/__init__.py @@ -0,0 +1,14 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import importlib +import os + + +# automatically import any Python files in the criterions/ directory +for file in sorted(os.listdir(os.path.dirname(__file__))): + if file.endswith(".py") and not file.startswith("_"): + module = file[: file.find(".py")] + importlib.import_module("fairseq.model_parallel.criterions." + module) diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/criterions/vocab_parallel_cross_entropy.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/criterions/vocab_parallel_cross_entropy.py new file mode 100644 index 00000000..35c50ee1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/criterions/vocab_parallel_cross_entropy.py @@ -0,0 +1,87 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +from fairseq import metrics, utils +from fairseq.criterions import FairseqCriterion, register_criterion + + +try: + from fairseq.model_parallel.megatron.mpu.cross_entropy import ( + vocab_parallel_cross_entropy, + ) + + has_megatron_submodule = True +except (ImportError, ModuleNotFoundError): + has_megatron_submodule = False + + +@register_criterion("vocab_parallel_cross_entropy") +class VocabParallelCrossEntropyCriterion(FairseqCriterion): + def __init__(self, task, sentence_avg): + super().__init__(task) + self.sentence_avg = sentence_avg + if not has_megatron_submodule: + raise ImportError( + "\n\nPlease install the megatron submodule:" + "\n\n git submodule update --init " + "fairseq/model_parallel/megatron" + ) + + def forward(self, model, sample, reduce=True): + """Compute the loss for the given sample. + + Returns a tuple with three elements: + 1) the loss + 2) the sample size, which is used as the denominator for the gradient + 3) logging outputs to display while training + """ + net_output = model(**sample["net_input"]) + target = sample["target"] + + loss = vocab_parallel_cross_entropy(net_output[0].float(), target) + loss = (loss * (target != self.padding_idx)).sum() + sample_size = ( + sample["target"].size(0) if self.sentence_avg else sample["ntokens"] + ) + logging_output = { + "loss": utils.item(loss.data) if reduce else loss.data, + "ntokens": sample["ntokens"], + "nsentences": sample["target"].size(0), + "sample_size": sample_size, + } + return loss, sample_size, logging_output + + @staticmethod + def reduce_metrics(logging_outputs) -> None: + """Aggregate logging outputs from data parallel training.""" + loss_sum = sum(log.get("loss", 0) for log in logging_outputs) + ntokens = sum(log.get("ntokens", 0) for log in logging_outputs) + sample_size = sum(log.get("sample_size", 0) for log in logging_outputs) + + metrics.log_scalar( + "loss", loss_sum / sample_size / math.log(2), sample_size, round=3 + ) + if sample_size != ntokens: + metrics.log_scalar( + "nll_loss", loss_sum / ntokens / math.log(2), ntokens, round=3 + ) + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["nll_loss"].avg) + ) + else: + metrics.log_derived( + "ppl", lambda meters: utils.get_perplexity(meters["loss"].avg) + ) + + @staticmethod + def logging_outputs_can_be_summed() -> bool: + """ + Whether the logging outputs returned by `forward` can be summed + across workers prior to calling `reduce_metrics`. Setting this + to True will improves distributed training speed. + """ + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/megatron_trainer.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/megatron_trainer.py new file mode 100644 index 00000000..ca421186 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/megatron_trainer.py @@ -0,0 +1,75 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +""" +Train a network across multiple GPUs. +""" + +from fairseq.dataclass.configs import FairseqConfig +from fairseq.distributed import utils as distributed_utils +from fairseq.trainer import Trainer + +try: + from fairseq.model_parallel.megatron.mpu import ( + get_data_parallel_rank, + get_data_parallel_world_size, + get_model_parallel_src_rank, + get_cuda_rng_tracker, + ) + + has_megatron_submodule = True +except (ImportError, ModuleNotFoundError): + has_megatron_submodule = False + + +class MegatronTrainer(Trainer): + """Main class for model parallel with data parallel training.""" + + def __init__(self, cfg: FairseqConfig, task, model, criterion, **kwargs): + if not has_megatron_submodule: + raise ImportError( + "\n\nPlease install the megatron submodule:" + "\n\n git submodule update --init " + "fairseq/model_parallel/megatron" + ) + super().__init__(cfg, task, model, criterion, **kwargs) + + def clip_grad_norm(self, clip_norm): + def _aggregate_model_parallel_grad_norm(total_norm): + total_norm = total_norm ** 2 + distributed_utils.all_reduce( + total_norm, group=distributed_utils.get_model_parallel_group() + ) + total_norm = total_norm ** 0.5 + return total_norm + + return self.optimizer.clip_grad_norm( + clip_norm, + aggregate_norm_fn=_aggregate_model_parallel_grad_norm, + ) + + def save_checkpoint(self, filename, extra_state): + """Save all training state in a checkpoint file.""" + extra_state["rng_tracker_states"] = get_cuda_rng_tracker().get_states() + super().save_checkpoint(filename, extra_state) + + def load_checkpoint( + self, + filename, + reset_optimizer=False, + reset_lr_scheduler=False, + optimizer_overrides=None, + reset_meters=False, + ): + extra_state = super().load_checkpoint( + filename, + reset_optimizer=reset_optimizer, + reset_lr_scheduler=reset_lr_scheduler, + optimizer_overrides=optimizer_overrides, + reset_meters=reset_meters, + ) + if extra_state is not None and "rng_tracker_states" in extra_state: + get_cuda_rng_tracker().set_states(extra_state["rng_tracker_states"]) + return extra_state diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/__init__.py new file mode 100644 index 00000000..3532479e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/__init__.py @@ -0,0 +1,20 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import importlib +import os + + +# automatically import any Python files in the models/ directory +models_dir = os.path.dirname(__file__) +for file in os.listdir(models_dir): + path = os.path.join(models_dir, file) + if ( + not file.startswith("_") + and not file.startswith(".") + and (file.endswith(".py") or os.path.isdir(path)) + ): + model_name = file[: file.find(".py")] if file.endswith(".py") else file + module = importlib.import_module("fairseq.model_parallel.models." + model_name) diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/__init__.py new file mode 100644 index 00000000..117827c3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/__init__.py @@ -0,0 +1,6 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .model import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/layers.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/layers.py new file mode 100644 index 00000000..85dbd44b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/layers.py @@ -0,0 +1,600 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from collections import namedtuple + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from fairseq import options, utils +from fairseq.modules import ( + AdaptiveSoftmax, + LayerNorm, + MultiheadAttention, + PositionalEmbedding, +) + +EncoderOut = namedtuple( + "TransformerEncoderOut", + [ + "encoder_out", # T x B x C + "encoder_padding_mask", # B x T + "encoder_embedding", # B x T x C + "encoder_states", # List[T x B x C] + ], +) + + +class TransformerEncoderEmbedding(nn.Module): + """Encoder Embedding + Positional Embedding""" + + def __init__(self, args, embed_tokens): + super().__init__() + self.dropout = args.dropout + self.max_source_positions = args.max_source_positions + self.embed_tokens = embed_tokens + if isinstance(embed_tokens, nn.ModuleList): + self.padding_idx = embed_tokens[0].padding_idx + embed_dim = sum(e.embedding_dim for e in embed_tokens) + else: + self.padding_idx = embed_tokens.padding_idx + embed_dim = embed_tokens.embedding_dim + self.embed_scale = math.sqrt(embed_dim) + self.embed_positions = ( + PositionalEmbedding( + args.max_source_positions, + embed_dim, + self.padding_idx, + learned=args.encoder_learned_pos, + ) + if not args.no_token_positional_embeddings + else None + ) + if getattr(args, "layernorm_embedding", False): + self.layernorm_embedding = LayerNorm(embed_dim) + else: + self.layernorm_embedding = None + + def forward(self, input): + # embed tokens and positions + src_tokens = input[0] + prev_output_tokens = input[2] + if isinstance(self.embed_tokens, nn.ModuleList): + x_embed_list = [] + for embed_tokens_part in self.embed_tokens: + x_embed_list.append(embed_tokens_part(src_tokens)) + + embedded = torch.cat(x_embed_list, dim=-1) + else: + embedded = self.embed_tokens(src_tokens) + x = embed = self.embed_scale * embedded + if self.embed_positions is not None: + x = embed + self.embed_positions(src_tokens) + if self.layernorm_embedding: + x = self.layernorm_embedding(x) + x = F.dropout(x, p=self.dropout, training=self.training) + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + # compute padding mask + encoder_padding_mask = src_tokens.eq(self.padding_idx) + return (x, encoder_padding_mask, prev_output_tokens) + + +class TransformerEncoderLayerNorm(nn.Module): + """ + Layer norm at the the end of all encoder layers if + args.encoder_enormalize_before = True + """ + + def __init__(self, args, embed_dim): + super().__init__() + if args.encoder_normalize_before: + self.layer_norm = LayerNorm(embed_dim) + else: + self.layer_norm = None + + def forward(self, input): + x = input[0] + encoder_padding_mask = input[1] + prev_output_tokens = input[2] + if self.layer_norm: + x = self.layer_norm(x) + # keeping track of the incremental_state is not supported yet + return (x, encoder_padding_mask, prev_output_tokens) + + +class TransformerDecoderEmbedding(nn.Module): + """Decoder Embedding + Positional Embedding""" + + def __init__(self, args, embed_tokens): + super().__init__() + self.dropout = args.dropout + self.share_input_output_embed = args.share_decoder_input_output_embed + input_embed_dim = ( + sum(e.embedding_dim for e in embed_tokens) + if isinstance(embed_tokens, nn.ModuleList) + else embed_tokens.embedding_dim + ) + embed_dim = args.decoder_embed_dim + self.output_embed_dim = args.decoder_output_dim + + padding_idx = ( + embed_tokens[0].padding_idx + if isinstance(embed_tokens, nn.ModuleList) + else embed_tokens.padding_idx + ) + self.max_target_positions = args.max_target_positions + + self.embed_tokens = embed_tokens + self.embed_scale = math.sqrt(embed_dim) # todo: try with input_embed_dim + + self.project_in_dim = ( + Linear(input_embed_dim, embed_dim, bias=False) + if embed_dim != input_embed_dim + else None + ) + + self.embed_positions = ( + PositionalEmbedding( + args.max_target_positions, + embed_dim, + padding_idx, + learned=args.decoder_learned_pos, + ) + if not args.no_token_positional_embeddings + else None + ) + + def forward(self, input): + mt_task = False + if isinstance(input, tuple): + if len(input) == 3: + encoder_out = input[0] + encoder_padding_mask = input[1] + prev_output_tokens = input[2] + incremental_state = None # Hardcoding to avoid passing of None objects + mt_task = True + else: + # HACK for now, need to fix (TODO sidgoyal) + prev_output_tokens = input[0] + # discard "src_lengths" + encoder_out = None + encoder_padding_mask = None + incremental_state = None + + else: + prev_output_tokens = input + encoder_out = None + encoder_padding_mask = None + incremental_state = None + + positions = ( + self.embed_positions( + prev_output_tokens, + incremental_state=incremental_state, + ) + if self.embed_positions is not None + else None + ) + + if incremental_state is not None: + prev_output_tokens = prev_output_tokens[:, -1:] + if positions is not None: + positions = positions[:, -1:] + + # embed tokens and positions + + if isinstance(self.embed_tokens, nn.ModuleList): + x_embed_list = [] + for embed_tokens_part in self.embed_tokens: + x_embed_list.append(embed_tokens_part(prev_output_tokens)) + + x = self.embed_scale * torch.cat(x_embed_list, dim=-1) + else: + x = self.embed_scale * self.embed_tokens(prev_output_tokens) + + if self.project_in_dim is not None: + x = self.project_in_dim(x) + + if positions is not None: + x += positions + x = F.dropout(x, p=self.dropout, training=self.training) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + if mt_task: + return (x, encoder_out, encoder_padding_mask) + return x + + +class TransformerDecoderOutputLayer(nn.Module): + def __init__(self, args, embed_tokens, dictionary): + super().__init__() + self.share_input_output_embed = args.share_decoder_input_output_embed + self.embed_tokens = embed_tokens + self.output_embed_dim = args.decoder_output_dim + embed_dim = args.decoder_embed_dim + + self.project_out_dim = ( + Linear(embed_dim, self.output_embed_dim, bias=False) + if embed_dim != self.output_embed_dim and not args.tie_adaptive_weights + else None + ) + self.adaptive_softmax = None + if args.adaptive_softmax_cutoff is not None: + assert not isinstance(embed_tokens, nn.ModuleList) + self.adaptive_softmax = AdaptiveSoftmax( + len(dictionary), + self.output_embed_dim, + options.eval_str_list(args.adaptive_softmax_cutoff, type=int), + dropout=args.adaptive_softmax_dropout, + adaptive_inputs=embed_tokens if args.tie_adaptive_weights else None, + factor=args.adaptive_softmax_factor, + tie_proj=args.tie_adaptive_proj, + ) + elif not self.share_input_output_embed: + self.embed_tokens = nn.Parameter( + torch.Tensor(len(dictionary), self.output_embed_dim) + ) + nn.init.normal_( + self.embed_tokens, mean=0, std=self.output_embed_dim**-0.5 + ) + + if args.decoder_normalize_before and not getattr( + args, "no_decoder_final_norm", False + ): + self.layer_norm = LayerNorm(embed_dim) + else: + self.layer_norm = None + + def forward(self, input, apply_final_proj=True): + if isinstance(input, tuple): + x = input[0] + else: + x = input + + if self.layer_norm: + x = self.layer_norm(x) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + if self.project_out_dim is not None: + x = self.project_out_dim(x) + if apply_final_proj: + x = self.output_layer(x) + return x + + def output_layer(self, features, **kwargs): + """Project features to the vocabulary size.""" + if self.adaptive_softmax is None: + # project back to size of vocabulary + if self.share_input_output_embed: + if isinstance(self.embed_tokens, nn.ModuleList): + output = None + for i, emb in enumerate(self.embed_tokens): + sidx = i * emb.embedding_dim + eidx = (i + 1) * emb.embedding_dim + if output is None: + output = F.linear(features[:, :, sidx:eidx], emb.weight) + else: + output += F.linear(features[:, :, sidx:eidx], emb.weight) + + return output + else: + return F.linear(features, self.embed_tokens.weight) + else: + return F.linear(features, self.embed_tokens) + else: + return features + + +class TransformerEncoderLayer(nn.Module): + """Encoder layer block. + In the original paper each operation (multi-head attention or FFN) is + postprocessed with: `dropout -> add residual -> layernorm`. In the + tensor2tensor code they suggest that learning is more robust when + preprocessing each layer with layernorm and postprocessing with: + `dropout -> add residual`. We default to the approach in the paper, but the + tensor2tensor approach can be enabled by setting + *args.encoder_normalize_before* to ``True``. + + Args: + args (argparse.Namespace): parsed command-line arguments + """ + + def __init__(self, args): + super().__init__() + self.embed_dim = args.encoder_embed_dim + self.self_attn = MultiheadAttention( + self.embed_dim, + args.encoder_attention_heads, + dropout=args.attention_dropout, + self_attention=True, + ) + self.self_attn_layer_norm = LayerNorm(self.embed_dim) + self.dropout = args.dropout + self.activation_fn = utils.get_activation_fn( + activation=getattr(args, "activation_fn", "relu") + ) + self.activation_dropout = getattr(args, "activation_dropout", 0) + if self.activation_dropout == 0: + # for backwards compatibility with models that use args.relu_dropout + self.activation_dropout = getattr(args, "relu_dropout", 0) + self.normalize_before = args.encoder_normalize_before + self.fc1 = Linear(self.embed_dim, args.encoder_ffn_embed_dim) + self.fc2 = Linear(args.encoder_ffn_embed_dim, self.embed_dim) + self.final_layer_norm = LayerNorm(self.embed_dim) + + def upgrade_state_dict_named(self, state_dict, name): + """ + Rename layer norm states from `...layer_norms.0.weight` to + `...self_attn_layer_norm.weight` and `...layer_norms.1.weight` to + `...final_layer_norm.weight` + """ + layer_norm_map = {"0": "self_attn_layer_norm", "1": "final_layer_norm"} + for old, new in layer_norm_map.items(): + for m in ("weight", "bias"): + k = "{}.layer_norms.{}.{}".format(name, old, m) + if k in state_dict: + state_dict["{}.{}.{}".format(name, new, m)] = state_dict[k] + del state_dict[k] + + def forward(self, input): + """ + Args: + input (Tuple): + input[0] (Tensor): input to the layer of shape `(seq_len, batch, embed_dim)` + input[1] (ByteTensor/FloatTensor): encoder padding mask - + binary ByteTensor of shape `(batch, src_len)` where padding elements + are indicated by ``1``. + input[2] (LongTensor): previous decoder outputs of shape + `(batch, tgt_len)`, for teacher forcing) + Returns: + output (Tuple): + output[0] (Tensor): encoded output of shape `(batch, src_len, embed_dim)` + output[1] (ByteTensor/FloatTensor): encoder padding mask + output[2] (LongTensor): previous decoder outputs + """ + x = input[0] + encoder_padding_mask = input[1] + prev_output_tokens = input[2] + residual = x + x = self.maybe_layer_norm(self.self_attn_layer_norm, x, before=True) + x, _ = self.self_attn( + query=x, key=x, value=x, key_padding_mask=encoder_padding_mask + ) + x = F.dropout(x, p=self.dropout, training=self.training) + x = residual + x + x = self.maybe_layer_norm(self.self_attn_layer_norm, x, after=True) + + residual = x + x = self.maybe_layer_norm(self.final_layer_norm, x, before=True) + x = self.activation_fn(self.fc1(x)) + x = F.dropout(x, p=self.activation_dropout, training=self.training) + x = self.fc2(x) + x = F.dropout(x, p=self.dropout, training=self.training) + x = residual + x + x = self.maybe_layer_norm(self.final_layer_norm, x, after=True) + return (x, encoder_padding_mask, prev_output_tokens) + + def maybe_layer_norm(self, layer_norm, x, before=False, after=False): + assert before ^ after + if after ^ self.normalize_before: + return layer_norm(x) + else: + return x + + +class TransformerDecoderLayer(nn.Module): + """Decoder layer block. + + In the original paper each operation (multi-head attention, encoder + attention or FFN) is postprocessed with: `dropout -> add residual -> + layernorm`. In the tensor2tensor code they suggest that learning is more + robust when preprocessing each layer with layernorm and postprocessing with: + `dropout -> add residual`. We default to the approach in the paper, but the + tensor2tensor approach can be enabled by setting + *args.decoder_normalize_before* to ``True``. + + Args: + args (argparse.Namespace): parsed command-line arguments + no_encoder_attn (bool, optional): whether to attend to encoder outputs + (default: False). + """ + + def __init__( + self, args, no_encoder_attn=False, add_bias_kv=False, add_zero_attn=False + ): + super().__init__() + self.embed_dim = args.decoder_embed_dim + self.self_attn = MultiheadAttention( + embed_dim=self.embed_dim, + num_heads=args.decoder_attention_heads, + dropout=args.attention_dropout, + add_bias_kv=add_bias_kv, + add_zero_attn=add_zero_attn, + self_attention=True, + ) + self.dropout = args.dropout + self.activation_fn = utils.get_activation_fn( + activation=getattr(args, "activation_fn", "relu") + ) + self.activation_dropout = getattr(args, "activation_dropout", 0) + if self.activation_dropout == 0: + # for backwards compatibility with models that use args.relu_dropout + self.activation_dropout = getattr(args, "relu_dropout", 0) + self.normalize_before = args.decoder_normalize_before + + # use layerNorm rather than FusedLayerNorm for exporting. + # char_inputs can be used to determint this. + # TODO remove this once we update apex with the fix + export = getattr(args, "char_inputs", False) + self.self_attn_layer_norm = LayerNorm(self.embed_dim, export=export) + + if no_encoder_attn: + self.encoder_attn = None + self.encoder_attn_layer_norm = None + else: + self.encoder_attn = MultiheadAttention( + self.embed_dim, + args.decoder_attention_heads, + kdim=getattr(args, "encoder_embed_dim", None), + vdim=getattr(args, "encoder_embed_dim", None), + dropout=args.attention_dropout, + encoder_decoder_attention=True, + ) + self.encoder_attn_layer_norm = LayerNorm(self.embed_dim, export=export) + + self.fc1 = Linear(self.embed_dim, args.decoder_ffn_embed_dim) + self.fc2 = Linear(args.decoder_ffn_embed_dim, self.embed_dim) + + self.final_layer_norm = LayerNorm(self.embed_dim, export=export) + self.need_attn = True + + self.onnx_trace = False + + def prepare_for_onnx_export_(self): + self.onnx_trace = True + + def forward(self, input): + """ + Args: + input (Tuple): + input[0] (Tensor): input to the layer of shape `(seq_len, batch, embed_dim)` + input[1] (Tensor): encoder output of shape `(batch, src_len, embed_dim)` + input[2] (ByteTensor/FloatTensor): encoder padding mask - + binary ByteTensor of shape `(batch, src_len)` where padding elements + are indicated by ``1``. + Returns: + output (Tuple): + output[0] (Tensor): encoded output of shape `(batch, src_len, embed_dim)` + output[1] (ByteTensor/FloatTensor): encoder padding mask + output[2] (LongTensor): previous decoder outputs + """ + # Note: incremental state is not yet supported + mt_task = False + if isinstance(input, tuple): + x = input[0] + encoder_out = input[1] + encoder_padding_mask = input[2] + incremental_state = None + mt_task = True + else: + x = input + encoder_out = None + encoder_padding_mask = None + incremental_state = None + + if incremental_state is None: + self_attn_mask = self.buffered_future_mask(x) + else: + self_attn_mask = None + + # TODO: add back prev_self_attn_state, prev_attn_state, + # self_attn_padding_mask + prev_self_attn_state = None + prev_attn_state = None + self_attn_padding_mask = None + + residual = x + x = self.maybe_layer_norm(self.self_attn_layer_norm, x, before=True) + if prev_self_attn_state is not None: + if incremental_state is None: + incremental_state = {} + prev_key, prev_value = prev_self_attn_state + saved_state = {"prev_key": prev_key, "prev_value": prev_value} + self.self_attn._set_input_buffer(incremental_state, saved_state) + x, attn = self.self_attn( + query=x, + key=x, + value=x, + key_padding_mask=self_attn_padding_mask, + incremental_state=incremental_state, + need_weights=False, + attn_mask=self_attn_mask, + ) + x = F.dropout(x, p=self.dropout, training=self.training) + x = residual + x + x = self.maybe_layer_norm(self.self_attn_layer_norm, x, after=True) + + if self.encoder_attn is not None: + residual = x + x = self.maybe_layer_norm(self.encoder_attn_layer_norm, x, before=True) + if prev_attn_state is not None: + if incremental_state is None: + incremental_state = {} + prev_key, prev_value = prev_attn_state + saved_state = {"prev_key": prev_key, "prev_value": prev_value} + self.encoder_attn._set_input_buffer(incremental_state, saved_state) + x, attn = self.encoder_attn( + query=x, + key=encoder_out, + value=encoder_out, + key_padding_mask=encoder_padding_mask, + incremental_state=incremental_state, + static_kv=True, + need_weights=(not self.training and self.need_attn), + ) + x = F.dropout(x, p=self.dropout, training=self.training) + x = residual + x + x = self.maybe_layer_norm(self.encoder_attn_layer_norm, x, after=True) + + residual = x + x = self.maybe_layer_norm(self.final_layer_norm, x, before=True) + x = self.activation_fn(self.fc1(x)) + x = F.dropout(x, p=self.activation_dropout, training=self.training) + x = self.fc2(x) + x = F.dropout(x, p=self.dropout, training=self.training) + x = residual + x + x = self.maybe_layer_norm(self.final_layer_norm, x, after=True) + + if mt_task: + return (x, encoder_out, encoder_padding_mask) + return x + + def buffered_future_mask(self, tensor): + dim = tensor.size(0) + if ( + not hasattr(self, "_future_mask") + or self._future_mask is None + or self._future_mask.device != tensor.device + ): + self._future_mask = torch.triu( + utils.fill_with_neg_inf(tensor.new(dim, dim)), 1 + ) + if self._future_mask.size(0) < dim: + self._future_mask = torch.triu( + utils.fill_with_neg_inf(self._future_mask.resize_(dim, dim)), 1 + ) + return self._future_mask[:dim, :dim] + + def maybe_layer_norm(self, layer_norm, x, before=False, after=False): + assert before ^ after + if after ^ self.normalize_before: + return layer_norm(x) + else: + return x + + def make_generation_fast_(self, need_attn=False, **kwargs): + self.need_attn = need_attn + + +def Embedding(num_embeddings, embedding_dim, padding_idx): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + nn.init.normal_(m.weight, mean=0, std=embedding_dim**-0.5) + nn.init.constant_(m.weight[padding_idx], 0) + return m + + +def Linear(in_features, out_features, bias=True): + m = nn.Linear(in_features, out_features, bias) + nn.init.xavier_uniform_(m.weight) + if bias: + nn.init.constant_(m.bias, 0.0) + return m diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/model.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/model.py new file mode 100644 index 00000000..7bb0c9ad --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/pipeline_parallel_transformer/model.py @@ -0,0 +1,789 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.model_parallel.models.pipeline_parallel_transformer.layers import ( + Embedding, + TransformerDecoderEmbedding, + TransformerDecoderLayer, + TransformerDecoderOutputLayer, + TransformerEncoderEmbedding, + TransformerEncoderLayer, + TransformerEncoderLayerNorm, +) +from fairseq.models import ( + BaseFairseqModel, + FairseqDecoder, + FairseqEncoder, + register_model, + register_model_architecture, +) +from fairseq.models.fairseq_encoder import EncoderOut +from fairseq.models.transformer import ( + base_architecture, + transformer_iwslt_de_en, + transformer_wmt_en_de_big, +) +from fairseq.modules import SinusoidalPositionalEmbedding + + +logger = logging.getLogger(__name__) + + +DEFAULT_MAX_SOURCE_POSITIONS = 1024 +DEFAULT_MAX_TARGET_POSITIONS = 1024 +TORCH_PIPE = False +RPC_INIT = False + + +def import_pipe(): + global TORCH_PIPE + global RPC_INIT + try: + from torch.distributed.pipeline.sync import Pipe # noqa + + global Pipe + from torch.distributed.pipeline.sync.utils import partition_model + + global partition_model + from torch.distributed import rpc + import tempfile + + TORCH_PIPE = True + # Initialize single process RPC agent since TORCH_PIPE requires + # RRef. RRef depends on RPC being initialized and as a result we initialize + # RPC with a single node. + tmpfile = tempfile.NamedTemporaryFile() + if not RPC_INIT: + rpc.init_rpc( + name="worker", + rank=0, + world_size=1, + rpc_backend_options=rpc.TensorPipeRpcBackendOptions( + init_method="file://{}".format(tmpfile.name), + ), + ) + RPC_INIT = True + logger.info("Using torch pipe") + except ImportError: + try: + from fairscale.nn import Pipe # noqa + + logger.info("Using fairscale pipe") + except ImportError: + raise ImportError("Please install fairscale with: pip install fairscale") + + +@register_model("pipeline_parallel_transformer") +class PipelineParallelTransformerModel(BaseFairseqModel): + def __init__(self, encoder, decoder, balance, devices, chunks, checkpoint): + import_pipe() + super().__init__() + assert isinstance(encoder, FairseqEncoder) + assert isinstance(decoder, FairseqDecoder) + encoder_module_list = ( + [encoder.embedding_layer] + + list(encoder.encoder_layers) + + [encoder.final_layer_norm] + ) + self.num_encoder_modules = len(encoder_module_list) + decoder_module_list = ( + [decoder.embedding_layer] + + list(decoder.decoder_layers) + + [decoder.decoder_output_layer] + ) + self.num_decoder_modules = len(decoder_module_list) + module_list = encoder_module_list + decoder_module_list + self.devices = devices + if TORCH_PIPE: + self.model = Pipe( + partition_model(nn.Sequential(*module_list), balance, devices), + chunks=chunks, + checkpoint=checkpoint, + ) + else: + self.model = Pipe( + nn.Sequential(*module_list), + balance=balance, + devices=devices, + chunks=chunks, + checkpoint=checkpoint, + ) + self.encoder_max_positions = self.max_positions_helper( + encoder.embedding_layer, "max_source_positions" + ) + self.decoder_max_positions = self.max_positions_helper( + decoder.embedding_layer, "max_target_positions" + ) + self.adaptive_softmax = getattr(decoder, "adaptive_softmax", None) + # Note: To be populated during inference + self.encoder = None + self.decoder = None + + def forward(self, src_tokens, src_lengths, prev_output_tokens): + if self.training: + input_lst = [src_tokens, src_lengths, prev_output_tokens] + input = tuple(i.to(self.devices[0], non_blocking=True) for i in input_lst) + if TORCH_PIPE: + return self.model(input).local_value() + else: + return self.model(input) + else: + assert self.encoder is not None and self.decoder is not None, ( + "encoder and decoder need to be initialized by " + + "calling the `prepare_for_inference_()` method" + ) + encoder_output_tuple = self.encoder(input) + return self.decoder(encoder_output_tuple) + + def prepare_for_inference_(self, cfg): + if self.encoder is not None and self.decoder is not None: + logger.info("Encoder and Decoder already initialized") + return + encoder_module_list = [] + decoder_module_list = [] + module_count = 0 + for partition in self.model.partitions: + for module in partition: + if module_count < self.num_encoder_modules: + encoder_module_list.append(module) + else: + decoder_module_list.append(module) + module_count += 1 + self.model = None + self.encoder = TransformerEncoder( + cfg.distributed_training, None, None, encoder_module_list + ) + self.decoder = TransformerDecoder( + cfg.distributed_training, + None, + None, + decoder_module_list=decoder_module_list, + ) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--activation-fn', + choices=utils.get_available_activation_fns(), + help='activation function to use') + parser.add_argument('--dropout', type=float, metavar='D', + help='dropout probability') + parser.add_argument('--attention-dropout', type=float, metavar='D', + help='dropout probability for attention weights') + parser.add_argument('--activation-dropout', '--relu-dropout', type=float, metavar='D', + help='dropout probability after activation in FFN.') + parser.add_argument('--encoder-embed-path', type=str, metavar='STR', + help='path to pre-trained encoder embedding') + parser.add_argument('--encoder-embed-dim', type=int, metavar='N', + help='encoder embedding dimension') + parser.add_argument('--encoder-ffn-embed-dim', type=int, metavar='N', + help='encoder embedding dimension for FFN') + parser.add_argument('--encoder-layers', type=int, metavar='N', + help='num encoder layers') + parser.add_argument('--encoder-attention-heads', type=int, metavar='N', + help='num encoder attention heads') + parser.add_argument('--encoder-normalize-before', action='store_true', + help='apply layernorm before each encoder block') + parser.add_argument('--encoder-learned-pos', action='store_true', + help='use learned positional embeddings in the encoder') + parser.add_argument('--decoder-embed-path', type=str, metavar='STR', + help='path to pre-trained decoder embedding') + parser.add_argument('--decoder-embed-dim', type=int, metavar='N', + help='decoder embedding dimension') + parser.add_argument('--decoder-ffn-embed-dim', type=int, metavar='N', + help='decoder embedding dimension for FFN') + parser.add_argument('--decoder-layers', type=int, metavar='N', + help='num decoder layers') + parser.add_argument('--decoder-attention-heads', type=int, metavar='N', + help='num decoder attention heads') + parser.add_argument('--decoder-learned-pos', action='store_true', + help='use learned positional embeddings in the decoder') + parser.add_argument('--decoder-normalize-before', action='store_true', + help='apply layernorm before each decoder block') + parser.add_argument('--share-decoder-input-output-embed', action='store_true', + help='share decoder input and output embeddings') + parser.add_argument('--share-all-embeddings', action='store_true', + help='share encoder, decoder and output embeddings' + ' (requires shared dictionary and embed dim)') + parser.add_argument('--no-token-positional-embeddings', default=False, action='store_true', + help='if set, disables positional embeddings (outside self attention)') + parser.add_argument('--adaptive-softmax-cutoff', metavar='EXPR', + help='comma separated list of adaptive softmax cutoff points. ' + 'Must be used with adaptive_loss criterion'), + parser.add_argument('--adaptive-softmax-dropout', type=float, metavar='D', + help='sets adaptive softmax dropout for the tail projections') + parser.add_argument('--num-embedding-chunks', type=int, metavar='N', default=1, + help='Number of embedding layer chunks (enables more even distribution' + 'of optimizer states across data parallel nodes' + 'when using optimizer state sharding and' + 'a big embedding vocabulary)') + # fmt: on + + @classmethod + def build_model_base(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present in older models + base_architecture(args) + + if not hasattr(args, "max_source_positions"): + args.max_source_positions = DEFAULT_MAX_SOURCE_POSITIONS + if not hasattr(args, "max_target_positions"): + args.max_target_positions = DEFAULT_MAX_TARGET_POSITIONS + + src_dict, tgt_dict = task.source_dictionary, task.target_dictionary + + def build_embedding(dictionary, embed_dim, path=None, num_embed_chunks=1): + assert embed_dim % num_embed_chunks == 0, ( + f"Number of embedding chunks = {num_embed_chunks} should be " + + f"divisible by the embedding dimension = {embed_dim}" + ) + assert path is None or num_embed_chunks == 1, ( + "Loading embedding from a path with number of embedding chunks > 1" + + " is not yet supported" + ) + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + # if provided, load from preloaded dictionaries + if path: + emb = Embedding(num_embeddings, embed_dim, padding_idx) + embed_dict = utils.parse_embedding(path) + utils.load_embedding(embed_dict, dictionary, emb) + else: + embed_chunk_dim = embed_dim // num_embed_chunks + emb = nn.ModuleList() + for i in range(num_embed_chunks): + emb.append(Embedding(num_embeddings, embed_chunk_dim, padding_idx)) + return emb + + num_embed_chunks = args.num_embedding_chunks + if args.share_all_embeddings: + if src_dict != tgt_dict: + raise ValueError("--share-all-embeddings requires a joined dictionary") + if args.encoder_embed_dim != args.decoder_embed_dim: + raise ValueError( + "--share-all-embeddings requires --encoder-embed-dim to match --decoder-embed-dim" + ) + if args.decoder_embed_path and ( + args.decoder_embed_path != args.encoder_embed_path + ): + raise ValueError( + "--share-all-embeddings not compatible with --decoder-embed-path" + ) + encoder_embed_tokens = build_embedding( + src_dict, + args.encoder_embed_dim, + args.encoder_embed_path, + num_embed_chunks, + ) + decoder_embed_tokens = encoder_embed_tokens + args.share_decoder_input_output_embed = True + else: + assert args.share_decoder_input_output_embed or num_embed_chunks == 1, ( + "Not sharing decoder I/O embeddings is not yet supported with number of " + + "embedding chunks > 1" + ) + encoder_embed_tokens = build_embedding( + src_dict, + args.encoder_embed_dim, + args.encoder_embed_path, + num_embed_chunks, + ) + decoder_embed_tokens = build_embedding( + tgt_dict, + args.decoder_embed_dim, + args.decoder_embed_path, + num_embed_chunks, + ) + + encoder = cls.build_encoder(args, src_dict, encoder_embed_tokens) + decoder = cls.build_decoder(args, tgt_dict, decoder_embed_tokens) + return (encoder, decoder) + + @classmethod + def build_encoder(cls, args, src_dict, embed_tokens): + return TransformerEncoder(args, src_dict, embed_tokens) + + @classmethod + def build_decoder(cls, args, tgt_dict, embed_tokens): + return TransformerDecoder(args, tgt_dict, embed_tokens) + + @classmethod + def build_model(cls, args, task): + encoder, decoder = cls.build_model_base(args, task) + return PipelineParallelTransformerModel( + encoder=encoder, + decoder=decoder, + balance=utils.eval_str_list(args.pipeline_balance, type=int), + devices=utils.eval_str_list(args.pipeline_devices, type=int), + chunks=args.pipeline_chunks, + checkpoint=args.pipeline_checkpoint, + ) + + def output_layer(self, features, **kwargs): + """Project features to the default output size (typically vocabulary size).""" + return self.decoder.output_layer(features, **kwargs) + + def max_positions(self): + """Maximum length supported by the model.""" + return (self.encoder_max_positions, self.decoder_max_positions) + + def max_positions_helper( + self, embedding_layer, max_positions_field="max_source_positions" + ): + """Maximum input length supported by the encoder or decoder.""" + if embedding_layer.embed_positions is None: + return getattr(embedding_layer, max_positions_field) + return min( + getattr(embedding_layer, max_positions_field), + embedding_layer.embed_positions.max_positions, + ) + + def get_normalized_probs(self, net_output, log_probs, sample=None): + """Get normalized probabilities (or log probs) from a net's output.""" + + if hasattr(self, "adaptive_softmax") and self.adaptive_softmax is not None: + if sample is not None: + assert "target" in sample + target = sample["target"] + else: + target = None + out = self.adaptive_softmax.get_log_prob(net_output, target=target) + return out.exp_() if not log_probs else out + + # A Pipe() module returns a tuple of tensors as the output. + # In this case, the tuple has one element - the output tensor of logits + logits = net_output if isinstance(net_output, torch.Tensor) else net_output[0] + if log_probs: + return utils.log_softmax(logits, dim=-1, onnx_trace=False) + else: + return utils.softmax(logits, dim=-1, onnx_trace=False) + + def max_decoder_positions(self): + """Maximum length supported by the decoder.""" + return self.decoder_max_positions + + def load_state_dict(self, state_dict, strict=True, model_cfg=None): + """Copies parameters and buffers from *state_dict* into this module and + its descendants. + + Overrides the method in :class:`nn.Module`. Compared with that method + this additionally "upgrades" *state_dicts* from old checkpoints. + """ + self.upgrade_state_dict(state_dict) + is_regular_transformer = not any("model.partitions" in k for k in state_dict) + if is_regular_transformer: + state_dict = self.convert_to_pipeline_parallel_state_dict(state_dict) + return super().load_state_dict(state_dict, strict) + + def convert_to_pipeline_parallel_state_dict(self, state_dict): + new_state_dict = self.state_dict() + encoder_layer_idx = 0 + decoder_layer_idx = 0 + encoder_key_suffixes = [ + "self_attn.k_proj.weight", + "self_attn.k_proj.bias", + "self_attn.v_proj.weight", + "self_attn.v_proj.bias", + "self_attn.q_proj.weight", + "self_attn.q_proj.bias", + "self_attn.out_proj.weight", + "self_attn.out_proj.bias", + "self_attn_layer_norm.weight", + "self_attn_layer_norm.bias", + "fc1.weight", + "fc1.bias", + "fc2.weight", + "fc2.bias", + "final_layer_norm.weight", + "final_layer_norm.bias", + ] + decoder_key_suffixes = [ + "self_attn.k_proj.weight", + "self_attn.k_proj.bias", + "self_attn.v_proj.weight", + "self_attn.v_proj.bias", + "self_attn.q_proj.weight", + "self_attn.q_proj.bias", + "self_attn.out_proj.weight", + "self_attn.out_proj.bias", + "self_attn_layer_norm.weight", + "self_attn_layer_norm.bias", + "encoder_attn.k_proj.weight", + "encoder_attn.k_proj.bias", + "encoder_attn.v_proj.weight", + "encoder_attn.v_proj.bias", + "encoder_attn.q_proj.weight", + "encoder_attn.q_proj.bias", + "encoder_attn.out_proj.weight", + "encoder_attn.out_proj.bias", + "encoder_attn_layer_norm.weight", + "encoder_attn_layer_norm.bias", + "fc1.weight", + "fc1.bias", + "fc2.weight", + "fc2.bias", + "final_layer_norm.weight", + "final_layer_norm.bias", + ] + for pid, partition in enumerate(self.model.partitions): + logger.info(f"Begin Partition {pid}") + for mid, module in enumerate(partition): + # fmt: off + if isinstance(module, TransformerEncoderEmbedding): + new_state_dict[f'model.partitions.{pid}.{mid}.embed_tokens.weight'] = state_dict['encoder.embed_tokens.weight'] + new_state_dict[f'model.partitions.{pid}.{mid}.embed_positions._float_tensor'] = state_dict['encoder.embed_positions._float_tensor'] + if isinstance(module, TransformerEncoderLayer): + for suffix in encoder_key_suffixes: + new_state_dict[f'model.partitions.{pid}.{mid}.{suffix}'] = state_dict[f'encoder.layers.{encoder_layer_idx}.{suffix}'] + encoder_layer_idx += 1 + if isinstance(module, TransformerDecoderLayer): + for suffix in decoder_key_suffixes: + new_state_dict[f'model.partitions.{pid}.{mid}.{suffix}'] = state_dict[f'decoder.layers.{decoder_layer_idx}.{suffix}'] + decoder_layer_idx += 1 + if isinstance(module, TransformerEncoderLayerNorm): + if 'encoder.layer_norm.weight' in state_dict: + new_state_dict[f'model.partitions.{pid}.{mid}.layer_norm.weight'] = state_dict['encoder.layer_norm.weight'] + new_state_dict[f'model.partitions.{pid}.{mid}.layer_norm.bias'] = state_dict['encoder.layer_norm.bias'] + if isinstance(module, TransformerDecoderEmbedding): + new_state_dict[f'model.partitions.{pid}.{mid}.embed_tokens.weight'] = state_dict['decoder.embed_tokens.weight'] + new_state_dict[f'model.partitions.{pid}.{mid}.embed_positions._float_tensor'] = state_dict['decoder.embed_positions._float_tensor'] + if isinstance(module, TransformerDecoderOutputLayer): + new_state_dict[f'model.partitions.{pid}.{mid}.output_projection.weight'] = state_dict['decoder.output_projection.weight'] + # fmt: on + return new_state_dict + + +class TransformerEncoder(FairseqEncoder): + """ + Transformer encoder consisting of *args.encoder_layers* layers. Each layer + is a :class:`TransformerEncoderLayer`. + + Args: + args (argparse.Namespace): parsed command-line arguments + dictionary (~fairseq.data.Dictionary): encoding dictionary + embed_tokens (torch.nn.Embedding): input embedding + """ + + def __init__(self, args, dictionary, embed_tokens, encoder_module_list=None): + super().__init__(dictionary) + self.register_buffer("version", torch.Tensor([3])) + import_pipe() + self.use_pipeline = encoder_module_list is not None + if not self.use_pipeline: + self.embedding_layer = TransformerEncoderEmbedding(args, embed_tokens) + self.encoder_layers = nn.Sequential( + *[TransformerEncoderLayer(args) for i in range(args.encoder_layers)] + ) + if isinstance(embed_tokens, nn.ModuleList): + emb_dim = sum(e.embedding_dim for e in embed_tokens) + else: + emb_dim = embed_tokens.embedding_dim + self.final_layer_norm = TransformerEncoderLayerNorm(args, emb_dim) + else: + encoder_balance = utils.eval_str_list( + args.pipeline_encoder_balance, type=int + ) + encoder_devices = utils.eval_str_list( + args.pipeline_encoder_devices, type=int + ) + assert sum(encoder_balance) == len(encoder_module_list), ( + f"Sum of encoder_balance={encoder_balance} is not equal " + + f"to num_encoder_modules={len(encoder_module_list)}" + ) + if TORCH_PIPE: + self.model = Pipe( + module=partition_model( + nn.Sequential(*encoder_module_list), + encoder_balance, + encoder_devices, + ), + chunks=args.pipeline_chunks, + checkpoint=args.pipeline_checkpoint, + ) + else: + self.model = Pipe( + module=nn.Sequential(*encoder_module_list), + balance=encoder_balance, + devices=encoder_devices, + chunks=args.pipeline_chunks, + checkpoint=args.pipeline_checkpoint, + ) + + def forward(self, src_tokens, src_lengths): + """ + Args: + input_tuple( + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (torch.LongTensor): lengths of each source sentence of + shape `(batch)` + ) + + Returns: + output_tuple( + - **encoder_out** (Tensor): the last encoder layer's output of + shape `(src_len, batch, embed_dim)` + - **encoder_padding_mask** (ByteTensor): the positions of + padding elements of shape `(batch, src_len)` + - prev_output_tokens + - **encoder_states** (List[Tensor]): all intermediate + hidden states of shape `(src_len, batch, embed_dim)`. + Only populated if *return_all_hiddens* is True. + ) + """ + dummy_prev_output_tokens = torch.zeros( + 1, dtype=src_tokens.dtype, device=src_tokens.device + ) + input_tuple = (src_tokens, src_lengths, dummy_prev_output_tokens) + if self.use_pipeline: + input_tuple = tuple(i.to(self.model.devices[0]) for i in input_tuple) + if TORCH_PIPE: + encoder_out = self.model(input_tuple).local_value() + else: + encoder_out = self.model(input_tuple) + else: + encoder_embed_output_tuple = self.embedding_layer(input_tuple) + encoder_layers_output = self.encoder_layers(encoder_embed_output_tuple) + encoder_out = self.final_layer_norm(encoder_layers_output) + # first element is the encoder output + # second element is the encoder padding mask + # the remaining elements of EncoderOut are not computed by + # the PipelineParallelTransformer + return EncoderOut(encoder_out[0], encoder_out[1], None, None, None, None) + + def reorder_encoder_out(self, encoder_out, new_order): + """ + Reorder encoder output according to *new_order*. + + Args: + encoder_out: output from the ``forward()`` method + new_order (LongTensor): desired order + + Returns: + *encoder_out* rearranged according to *new_order* + """ + if encoder_out.encoder_out is not None: + encoder_out = encoder_out._replace( + encoder_out=encoder_out.encoder_out.index_select(1, new_order) + ) + if encoder_out.encoder_padding_mask is not None: + encoder_out = encoder_out._replace( + encoder_padding_mask=encoder_out.encoder_padding_mask.index_select( + 0, new_order + ) + ) + if encoder_out.encoder_embedding is not None: + encoder_out = encoder_out._replace( + encoder_embedding=encoder_out.encoder_embedding.index_select( + 0, new_order + ) + ) + if encoder_out.encoder_states is not None: + for idx, state in enumerate(encoder_out.encoder_states): + encoder_out.encoder_states[idx] = state.index_select(1, new_order) + return encoder_out + + def max_positions(self): + """Maximum input length supported by the encoder.""" + if self.embedding_layer.embed_positions is None: + return self.embedding_layer.max_source_positions + return min( + self.embedding_layer.max_source_positions, + self.embedding_layer.embed_positions.max_positions, + ) + + +class TransformerDecoder(FairseqDecoder): + """ + Transformer decoder consisting of *args.decoder_layers* layers. Each layer + is a :class:`TransformerDecoderLayer`. + + Args: + args (argparse.Namespace): parsed command-line arguments + dictionary (~fairseq.data.Dictionary): decoding dictionary + embed_tokens (torch.nn.Embedding): output embedding + no_encoder_attn (bool, optional): whether to attend to encoder outputs + (default: False). + """ + + def __init__( + self, + args, + dictionary, + embed_tokens, + no_encoder_attn=False, + decoder_module_list=None, + ): + super().__init__(dictionary) + self.register_buffer("version", torch.Tensor([3])) + import_pipe() + self.use_pipeline = decoder_module_list is not None + if not self.use_pipeline: + self.embedding_layer = TransformerDecoderEmbedding(args, embed_tokens) + self.decoder_layers = nn.Sequential( + *[ + TransformerDecoderLayer(args, no_encoder_attn) + for _ in range(args.decoder_layers) + ] + ) + self.decoder_output_layer = TransformerDecoderOutputLayer( + args, embed_tokens, dictionary + ) + else: + decoder_balance = utils.eval_str_list( + args.pipeline_decoder_balance, type=int + ) + decoder_devices = utils.eval_str_list( + args.pipeline_decoder_devices, type=int + ) + assert sum(decoder_balance) == len(decoder_module_list), ( + f"Sum of decoder_balance={decoder_balance} is not equal " + + f"to num_decoder_modules={len(decoder_module_list)}" + ) + if TORCH_PIPE: + self.model = Pipe( + module=partition_model( + nn.Sequential(*decoder_module_list), + decoder_balance, + decoder_devices, + ), + chunks=args.pipeline_chunks, + checkpoint=args.pipeline_checkpoint, + ) + else: + self.model = Pipe( + module=nn.Sequential(*decoder_module_list), + balance=decoder_balance, + devices=decoder_devices, + chunks=args.pipeline_chunks, + checkpoint=args.pipeline_checkpoint, + ) + + def forward( + self, + prev_output_tokens, + encoder_out=None, + ): + """ + Args: + prev_output_tokens (LongTensor): previous decoder outputs of shape + `(batch, tgt_len)`, for teacher forcing + encoder_out (optional): output from the encoder, used for + encoder-side attention + incremental_state (dict): dictionary used for storing state during + :ref:`Incremental decoding` + features_only (bool, optional): only return features without + applying output layer (default: False). + + Returns: + tuple: + - the decoder's output of shape `(batch, tgt_len, vocab)` + - a dictionary with any model-specific outputs + """ + input_tuple = ( + encoder_out.encoder_out, + encoder_out.encoder_padding_mask, + prev_output_tokens, + ) + if self.use_pipeline: + input_tuple = tuple(i.to(self.model.devices[0]) for i in input_tuple) + if TORCH_PIPE: + return (self.model(input_tuple).local_value(),) + else: + return (self.model(input_tuple),) + else: + embed_layer_output = self.embedding_layer(input_tuple) + state = self.decoder_layers(embed_layer_output) + return (self.decoder_output_layer(state),) + + def output_layer(self, features, **kwargs): + """Project features to the vocabulary size.""" + if self.adaptive_softmax is None: + # project back to size of vocabulary + if self.share_input_output_embed: + return F.linear(features, self.embed_tokens.weight) + else: + return F.linear(features, self.embed_out) + else: + return features + + def max_positions(self): + """Maximum output length supported by the decoder.""" + if self.embedding_layer.embed_positions is None: + return self.embedding_layer.max_target_positions + return min( + self.embedding_layer.max_target_positions, + self.embedding_layer.embed_positions.max_positions, + ) + + def buffered_future_mask(self, tensor): + dim = tensor.size(0) + if ( + not hasattr(self, "_future_mask") + or self._future_mask is None + or self._future_mask.device != tensor.device + or self._future_mask.size(0) < dim + ): + self._future_mask = torch.triu( + utils.fill_with_neg_inf(tensor.new(dim, dim)), 1 + ) + return self._future_mask[:dim, :dim] + + def upgrade_state_dict_named(self, state_dict, name): + """Upgrade a (possibly old) state dict for new versions of fairseq.""" + if isinstance(self.embed_positions, SinusoidalPositionalEmbedding): + weights_key = "{}.embed_positions.weights".format(name) + if weights_key in state_dict: + del state_dict[weights_key] + state_dict[ + "{}.embed_positions._float_tensor".format(name) + ] = torch.FloatTensor(1) + + for i in range(len(self.layers)): + # update layer norms + layer_norm_map = { + "0": "self_attn_layer_norm", + "1": "encoder_attn_layer_norm", + "2": "final_layer_norm", + } + for old, new in layer_norm_map.items(): + for m in ("weight", "bias"): + k = "{}.layers.{}.layer_norms.{}.{}".format(name, i, old, m) + if k in state_dict: + state_dict[ + "{}.layers.{}.{}.{}".format(name, i, new, m) + ] = state_dict[k] + del state_dict[k] + + version_key = "{}.version".format(name) + if utils.item(state_dict.get(version_key, torch.Tensor([1]))[0]) <= 2: + # earlier checkpoints did not normalize after the stack of layers + self.layer_norm = None + self.normalize = False + state_dict[version_key] = torch.Tensor([1]) + + return state_dict + + +@register_model_architecture( + "pipeline_parallel_transformer", "transformer_iwslt_de_en_pipeline_parallel" +) +def transformer_iwslt_de_en_dist(args): + transformer_iwslt_de_en(args) + + +@register_model_architecture( + "pipeline_parallel_transformer", "transformer_wmt_en_de_big_pipeline_parallel" +) +def transformer_wmt_en_de_big_dist(args): + transformer_wmt_en_de_big(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/roberta/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/roberta/__init__.py new file mode 100644 index 00000000..117827c3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/roberta/__init__.py @@ -0,0 +1,6 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .model import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/roberta/model.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/roberta/model.py new file mode 100644 index 00000000..77a80ef7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/roberta/model.py @@ -0,0 +1,225 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +RoBERTa: A Robustly Optimized BERT Pretraining Approach. +""" + +import logging + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.model_parallel.models.transformer import ModelParallelTransformerEncoder +from fairseq.models import register_model, register_model_architecture +from fairseq.models.roberta import ( + roberta_base_architecture, + roberta_prenorm_architecture, + RobertaEncoder, + RobertaModel, +) +from fairseq.modules import LayerNorm + + +try: + from fairseq.model_parallel.megatron.mpu import ( + copy_to_model_parallel_region, + gather_from_model_parallel_region, + ColumnParallelLinear, + VocabParallelEmbedding, + ) + + has_megatron_submodule = True +except (ImportError, ModuleNotFoundError): + has_megatron_submodule = False + +logger = logging.getLogger(__name__) + + +@register_model("model_parallel_roberta") +class ModelParallelRobertaModel(RobertaModel): + def __init__(self, args, encoder): + super().__init__(args, encoder) + + self.classification_heads = nn.ModuleDict() + + @staticmethod + def add_args(parser): + RobertaModel.add_args(parser) + parser.add_argument( + "--no-final-layer-norm", + action="store_true", + help=( + "don't add final layernorm (only applicable when " + "--encoder-normalize-before=True" + ), + ) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present + base_architecture(args) + + task.source_dictionary.pad_to_multiple_(args.model_parallel_size * 8) + task.target_dictionary.pad_to_multiple_(args.model_parallel_size * 8) + + if not hasattr(args, "max_positions"): + args.max_positions = args.tokens_per_sample + + if getattr(args, "untie_weights_roberta", False): + raise NotImplementedError( + "--untie-weights-roberta is not supported in model parallel mode" + ) + + encoder = ModelParallelRobertaEncoder(args, task.source_dictionary) + return cls(args, encoder) + + def forward( + self, + src_tokens, + features_only=False, + return_all_hiddens=False, + classification_head_name=None, + **kwargs + ): + if classification_head_name is not None: + features_only = True + + x, extra = self.encoder(src_tokens, features_only, return_all_hiddens, **kwargs) + + if classification_head_name is not None: + x = self.classification_heads[classification_head_name](x) + return x, extra + + def register_classification_head( + self, name, num_classes=None, inner_dim=None, **kwargs + ): + """Register a classification head.""" + if name in self.classification_heads: + prev_num_classes = self.classification_heads[name].out_proj.out_features + prev_inner_dim = self.classification_heads[name].dense.out_features + if num_classes != prev_num_classes or inner_dim != prev_inner_dim: + logger.warning( + 're-registering head "{}" with num_classes {} (prev: {}) ' + "and inner_dim {} (prev: {})".format( + name, num_classes, prev_num_classes, inner_dim, prev_inner_dim + ) + ) + self.classification_heads[name] = ModelParallelRobertaClassificationHead( + self.args.encoder_embed_dim, + inner_dim or self.args.encoder_embed_dim, + num_classes, + self.args.pooler_activation_fn, + self.args.pooler_dropout, + ) + + +class ModelParallelRobertaLMHead(nn.Module): + """Head for masked language modeling.""" + + def __init__(self, embed_dim, output_dim, activation_fn, weight=None): + super().__init__() + self.dense = ColumnParallelLinear(embed_dim, embed_dim, gather_output=True) + self.activation_fn = utils.get_activation_fn(activation_fn) + self.layer_norm = LayerNorm(embed_dim) + + if weight is None: + weight = nn.Linear(embed_dim, output_dim, bias=False).weight + self.weight = weight + self.bias = nn.Parameter(torch.zeros(output_dim)) + + def forward(self, features, masked_tokens=None, **kwargs): + # Only project the unmasked tokens while training, + # saves both memory and computation + if masked_tokens is not None: + features = features[masked_tokens, :] + + x = self.dense(features) + x = self.activation_fn(x) + x = self.layer_norm(x) + + x = copy_to_model_parallel_region(x) + # project back to size of vocabulary with bias + x = F.linear(x, self.weight) + x = gather_from_model_parallel_region(x).contiguous() + x = x + self.bias + return x + + +class ModelParallelRobertaClassificationHead(nn.Module): + """Head for sentence-level classification tasks.""" + + def __init__( + self, input_dim, inner_dim, num_classes, activation_fn, pooler_dropout + ): + super().__init__() + self.dense = ColumnParallelLinear(input_dim, inner_dim, gather_output=True) + self.activation_fn = utils.get_activation_fn(activation_fn) + self.dropout = nn.Dropout(p=pooler_dropout) + self.out_proj = nn.Linear(inner_dim, num_classes) + + def forward(self, features, **kwargs): + x = features[:, 0, :] # take token (equiv. to [CLS]) + x = self.dropout(x) + x = self.dense(x) + x = self.activation_fn(x) + x = self.dropout(x) + x = self.out_proj(x) + return x + + +class ModelParallelRobertaEncoder(RobertaEncoder): + """RoBERTa encoder.""" + + def __init__(self, args, dictionary): + super().__init__(args, dictionary) + assert not self.args.untie_weights_roberta + + def build_embedding(self, vocab_size, embedding_dim, padding_idx): + return VocabParallelEmbedding(vocab_size, embedding_dim, padding_idx) + + def build_encoder(self, args, dictionary, embed_tokens): + return ModelParallelTransformerEncoder(args, dictionary, embed_tokens) + + def build_lm_head(self, embed_dim, output_dim, activation_fn, weight): + return ModelParallelRobertaLMHead(embed_dim, output_dim, activation_fn, weight) + + +@register_model_architecture("model_parallel_roberta", "model_parallel_roberta") +def base_architecture(args): + args.no_final_layer_norm = getattr(args, "no_final_layer_norm", False) + # model parallel RoBERTa defaults to "Pre-LN" formulation + roberta_prenorm_architecture(args) + + +# earlier versions of model parallel RoBERTa removed the final layer norm +@register_model_architecture("model_parallel_roberta", "model_parallel_roberta_v1") +def model_parallel_roberta_v1_architecture(args): + args.no_final_layer_norm = getattr(args, "no_final_layer_norm", True) + base_architecture(args) + + +@register_model_architecture( + "model_parallel_roberta", "model_parallel_roberta_postnorm" +) +def model_parallel_roberta_postnorm_architecture(args): + # the original BERT/RoBERTa uses the "Post-LN" formulation + roberta_base_architecture(args) + + +@register_model_architecture("model_parallel_roberta", "model_parallel_roberta_base") +def model_parallel_roberta_base_architecture(args): + base_architecture(args) + + +@register_model_architecture("model_parallel_roberta", "model_parallel_roberta_large") +def model_parallel_roberta_large_architecture(args): + args.encoder_layers = getattr(args, "encoder_layers", 24) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4096) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 16) + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/transformer.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/transformer.py new file mode 100644 index 00000000..cf3b2e8b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/transformer.py @@ -0,0 +1,121 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch.nn as nn + +from fairseq.model_parallel.modules import ( + ModelParallelTransformerDecoderLayer, + ModelParallelTransformerEncoderLayer, +) +from fairseq.models import register_model +from fairseq.models.transformer import ( + TransformerDecoder, + TransformerEncoder, + TransformerModel, +) + +try: + from fairseq.model_parallel.megatron.mpu import ( + VocabParallelEmbedding, + copy_to_model_parallel_region, + gather_from_model_parallel_region, + ) + + has_megatron_submodule = True +except (ImportError, ModuleNotFoundError): + has_megatron_submodule = False + + +logger = logging.getLogger(__name__) + + +@register_model("model_parallel_transformer") +class ModelParallelTransformerModel(TransformerModel): + """ + Model parallel Transformer model. + """ + + @classmethod + def build_embedding(cls, args, dictionary, embed_dim, path=None): + if not has_megatron_submodule: + raise ImportError( + "\n\nPlease install the megatron submodule:" + "\n\n git submodule update --init " + "fairseq/model_parallel/megatron" + ) + dictionary.pad_to_multiple_(args.model_parallel_size * 8) + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + + def _vocab_init(tensor, **kwargs): + nn.init.normal_(tensor, mean=0, std=num_embeddings**-0.5) + nn.init.constant_(tensor[1], 0) + + emb = VocabParallelEmbedding( + num_embeddings, embed_dim, padding_idx, init_method=_vocab_init + ) + # if provided, load from preloaded dictionaries + if path: + raise NotImplementedError( + "Loading of embedding from path is not supported for model parallel" + ) + return emb + + @classmethod + def build_encoder(cls, args, src_dict, embed_tokens): + return ModelParallelTransformerEncoder(args, src_dict, embed_tokens) + + @classmethod + def build_decoder(cls, args, tgt_dict, embed_tokens): + return ModelParallelTransformerDecoder( + args, + tgt_dict, + embed_tokens, + no_encoder_attn=getattr(args, "no_cross_attention", False), + ) + + +class ModelParallelTransformerEncoder(TransformerEncoder): + """ + Model parallel Transformer encoder consisting of *args.encoder_layers* layers. Each layer + is a :class:`ModelParallelTransformerEncoderLayer`. + """ + + def __init__(self, args, dictionary, embed_tokens): + super().__init__(args, dictionary, embed_tokens) + + if args.no_final_layer_norm: + self.layer_norm = None + + def build_encoder_layer(self, args): + return ModelParallelTransformerEncoderLayer(args) + + +class ModelParallelTransformerDecoder(TransformerDecoder): + """ + Model Parallel Transformer decoder consisting of *args.decoder_layers* layers. Each layer + is a :class:`ModelParallelTransformerDecoderLayer`. + """ + + def build_decoder_layer(self, args, no_encoder_attn=False): + return ModelParallelTransformerDecoderLayer(args, no_encoder_attn) + + def output_layer(self, features, **kwargs): + """Project features to the vocabulary size.""" + if not self.share_input_output_embed: + raise NotImplementedError( + "Model parallel training currently requires --share-decoder-input-output-embed" + ) + + features = copy_to_model_parallel_region(features) + + # project back to size of vocabulary + x = self.output_projection(features) + + if getattr(self.args, "criterion") != "vocab_parallel_cross_entropy": + x = gather_from_model_parallel_region(x).contiguous() + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/transformer_lm.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/transformer_lm.py new file mode 100644 index 00000000..03e4dbe2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/models/transformer_lm.py @@ -0,0 +1,169 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn as nn + +from fairseq.model_parallel.models.transformer import ModelParallelTransformerDecoder +from fairseq.models import register_model, register_model_architecture +from fairseq.models.transformer_lm import TransformerLanguageModel + +try: + from fairseq.model_parallel.megatron.mpu import VocabParallelEmbedding + + has_megatron_submodule = True +except (ImportError, ModuleNotFoundError): + has_megatron_submodule = False + + +DEFAULT_MAX_TARGET_POSITIONS = 1024 + + +@register_model("model_parallel_transformer_lm") +class ModelParallelTransformerLanguageModel(TransformerLanguageModel): + @staticmethod + def add_args(parser): + TransformerLanguageModel.add_args(parser) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + if not has_megatron_submodule: + raise ImportError( + "\n\nPlease install the megatron submodule:" + "\n\n git submodule update --init " + "fairseq/model_parallel/megatron" + ) + + # make sure all arguments are present in older models + base_lm_architecture(args) + + task.source_dictionary.pad_to_multiple_(args.model_parallel_size * 8) + task.target_dictionary.pad_to_multiple_(args.model_parallel_size * 8) + + if args.decoder_layers_to_keep: + args.decoder_layers = len(args.decoder_layers_to_keep.split(",")) + + if getattr(args, "max_target_positions", None) is None: + args.max_target_positions = getattr( + args, "tokens_per_sample", DEFAULT_MAX_TARGET_POSITIONS + ) + + if args.character_embeddings: + raise NotImplementedError( + "Character embeddings is not supported for model parallel" + ) + elif args.adaptive_input: + raise NotImplementedError( + "Adaptive input is not supported for model parallel" + ) + else: + embed_tokens = cls.build_embedding( + args, task.source_dictionary, args.decoder_input_dim + ) + + decoder = ModelParallelTransformerDecoder( + args, + task.target_dictionary, + embed_tokens, + no_encoder_attn=True, + ) + return cls(decoder) + + @classmethod + def build_embedding(cls, args, dictionary, embed_dim, path=None): + def _vocab_init(tensor, **kwargs): + nn.init.normal_(tensor, mean=0, std=embed_dim**-0.5) + nn.init.constant_(tensor[1], 0) + + embed_tokens = VocabParallelEmbedding( + len(dictionary), embed_dim, dictionary.pad(), init_method=_vocab_init + ) + return embed_tokens + + +def base_lm_architecture(args): + # backward compatibility for older model checkpoints + if hasattr(args, "no_tie_adaptive_proj"): + # previous models defined --no-tie-adaptive-proj, so use the existence of + # that option to determine if this is an "old" model checkpoint + args.no_decoder_final_norm = True # old models always set this to True + if args.no_tie_adaptive_proj is False: + args.tie_adaptive_proj = True + if hasattr(args, "decoder_final_norm"): + args.no_decoder_final_norm = not args.decoder_final_norm + + args.activation_fn = getattr(args, "activation_fn", "relu") + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.relu_dropout = getattr(args, "relu_dropout", 0.0) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 2048) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + # Model training is not stable without this + args.decoder_normalize_before = True + args.no_decoder_final_norm = getattr(args, "no_decoder_final_norm", False) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.adaptive_softmax_factor = getattr(args, "adaptive_softmax_factor", 4) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.character_embeddings = getattr(args, "character_embeddings", False) + args.character_filters = getattr( + args, + "character_filters", + "[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]", + ) + args.character_embedding_dim = getattr(args, "character_embedding_dim", 4) + args.char_embedder_highway_layers = getattr(args, "char_embedder_highway_layers", 2) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.adaptive_input_factor = getattr(args, "adaptive_input_factor", 4) + args.adaptive_input_cutoff = getattr(args, "adaptive_input_cutoff", None) + args.tie_adaptive_weights = getattr(args, "tie_adaptive_weights", False) + args.tie_adaptive_proj = getattr(args, "tie_adaptive_proj", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.decoder_layerdrop = getattr(args, "decoder_layerdrop", 0.0) + args.decoder_layers_to_keep = getattr(args, "decoder_layers_to_keep", None) + args.layernorm_embedding = getattr(args, "layernorm_embedding", False) + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + args.quant_noise_pq = getattr(args, "quant_noise_pq", 0.0) + args.quant_noise_pq_block_size = getattr(args, "quant_noise_pq_block_size", 8) + args.quant_noise_scalar = getattr(args, "quant_noise_scalar", 0.0) + args.add_bos_token = getattr(args, "add_bos_token", False) + + +@register_model_architecture("model_parallel_transformer_lm", "transformer_lm_megatron") +def transformer_lm_megatron(args): + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 3072) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 3072 * 4) + args.decoder_layers = getattr(args, "decoder_layers", 72) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 32) + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.activation_fn = getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) + + +@register_model_architecture( + "model_parallel_transformer_lm", "transformer_lm_megatron_11b" +) +def transformer_lm_megatron_11b(args): + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 3072) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 3072 * 6) + args.decoder_layers = getattr(args, "decoder_layers", 72) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 32) + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.activation_fn = getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/__init__.py new file mode 100644 index 00000000..11603217 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/__init__.py @@ -0,0 +1,17 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +from .multihead_attention import ModelParallelMultiheadAttention +from .transformer_layer import ( + ModelParallelTransformerEncoderLayer, + ModelParallelTransformerDecoderLayer, +) + +__all__ = [ + "ModelParallelMultiheadAttention", + "ModelParallelTransformerEncoderLayer", + "ModelParallelTransformerDecoderLayer", +] diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/multihead_attention.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/multihead_attention.py new file mode 100644 index 00000000..bbea4509 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/multihead_attention.py @@ -0,0 +1,349 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Dict, Optional, Tuple + +import torch +import torch.nn.functional as F +from torch import Tensor, nn + +from fairseq import utils +from fairseq.incremental_decoding_utils import with_incremental_state +from fairseq.modules.fairseq_dropout import FairseqDropout + +try: + from fairseq.model_parallel.megatron.mpu import ( + ColumnParallelLinear, + RowParallelLinear, + get_cuda_rng_tracker, + get_model_parallel_world_size, + ) + + has_megatron_submodule = True +except (ImportError, ModuleNotFoundError): + has_megatron_submodule = False + + +@with_incremental_state +class ModelParallelMultiheadAttention(nn.Module): + """Model parallel Multi-headed attention. + This performs the Multi-headed attention over multiple gpus. + + See "Megatron-LM: https://arxiv.org/pdf/1909.08053.pdf" for more details. + """ + + def __init__( + self, + embed_dim, + num_heads, + kdim=None, + vdim=None, + dropout=0.0, + bias=True, + self_attention=False, + encoder_decoder_attention=False, + ): + super().__init__() + if not has_megatron_submodule: + raise ImportError( + "\n\nPlease install the megatron submodule:" + "\n\n git submodule update --init " + "fairseq/model_parallel/megatron" + ) + self.embed_dim = embed_dim + self.kdim = kdim if kdim is not None else embed_dim + self.vdim = vdim if vdim is not None else embed_dim + self.qkv_same_dim = self.kdim == embed_dim and self.vdim == embed_dim + + self.model_parallel_size = get_model_parallel_world_size() + + self.num_heads_partition = num_heads // self.model_parallel_size + assert ( + self.num_heads_partition * self.model_parallel_size == num_heads + ), "Number of heads must be divisible by model parallel size" + + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + self.head_dim = embed_dim // num_heads + assert ( + self.head_dim * num_heads == self.embed_dim + ), "embed_dim must be divisible by num_heads" + self.scaling = self.head_dim**-0.5 + + self.self_attention = self_attention + self.encoder_decoder_attention = encoder_decoder_attention + + assert ( + not self.self_attention or self.qkv_same_dim + ), "Self-attention requires query, key and value to be of the same size" + + self.k_proj = ColumnParallelLinear( + self.kdim, embed_dim, bias=bias, gather_output=False + ) + self.v_proj = ColumnParallelLinear( + self.vdim, embed_dim, bias=bias, gather_output=False + ) + self.q_proj = ColumnParallelLinear( + embed_dim, embed_dim, bias=bias, gather_output=False + ) + self.out_proj = RowParallelLinear( + embed_dim, embed_dim, bias=bias, input_is_parallel=True + ) + + def forward( + self, + query, + key: Optional[Tensor], + value: Optional[Tensor], + key_padding_mask: Optional[Tensor] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + static_kv: bool = False, + attn_mask: Optional[Tensor] = None, + **unused_kwargs, + ) -> Tuple[Tensor, Optional[Tensor]]: + """Input shape: Time x Batch x Channel + + Args: + key_padding_mask (ByteTensor, optional): mask to exclude + keys that are pads, of shape `(batch, src_len)`, where + padding elements are indicated by 1s. + attn_mask (ByteTensor, optional): typically used to + implement causal attention, where the mask prevents the + attention from looking forward in time (default: None). + """ + tgt_len, bsz, embed_dim = query.size() + assert embed_dim == self.embed_dim + assert list(query.size()) == [tgt_len, bsz, embed_dim] + + is_tpu = query.device.type == "xla" + + if incremental_state is not None: + saved_state = self._get_input_buffer(incremental_state) + if saved_state is not None and "prev_key" in saved_state: + # previous time steps are cached - no need to recompute + # key and value if they are static + if static_kv: + assert self.encoder_decoder_attention and not self.self_attention + key = value = None + else: + saved_state = None + + if self.self_attention: + q = self.q_proj(query) + k = self.k_proj(query) + v = self.v_proj(query) + elif self.encoder_decoder_attention: + # encoder-decoder attention + q = self.q_proj(query) + if key is None: + assert value is None + k = v = None + else: + k = self.k_proj(key) + v = self.v_proj(key) + + else: + assert key is not None and value is not None + q = self.q_proj(query) + k = self.k_proj(key) + v = self.v_proj(value) + q *= self.scaling + + q = ( + q.contiguous() + .view(tgt_len, bsz * self.num_heads_partition, self.head_dim) + .transpose(0, 1) + ) + if k is not None: + k = ( + k.contiguous() + .view(-1, bsz * self.num_heads_partition, self.head_dim) + .transpose(0, 1) + ) + if v is not None: + v = ( + v.contiguous() + .view(-1, bsz * self.num_heads_partition, self.head_dim) + .transpose(0, 1) + ) + + if saved_state is not None: + # saved states are stored with shape (bsz, num_heads_partition, seq_len, head_dim) + if "prev_key" in saved_state: + _prev_key = saved_state["prev_key"] + assert _prev_key is not None + prev_key = _prev_key.view( + bsz * self.num_heads_partition, -1, self.head_dim + ) + if static_kv: + k = prev_key + else: + assert k is not None + k = torch.cat([prev_key, k], dim=1) + if "prev_value" in saved_state: + _prev_value = saved_state["prev_value"] + assert _prev_value is not None + prev_value = _prev_value.view( + bsz * self.num_heads_partition, -1, self.head_dim + ) + if static_kv: + v = prev_value + else: + assert v is not None + v = torch.cat([prev_value, v], dim=1) + prev_key_padding_mask: Optional[Tensor] = None + if "prev_key_padding_mask" in saved_state: + prev_key_padding_mask = saved_state["prev_key_padding_mask"] + assert k is not None and v is not None + key_padding_mask = ( + ModelParallelMultiheadAttention._append_prev_key_padding_mask( + key_padding_mask=key_padding_mask, + prev_key_padding_mask=prev_key_padding_mask, + batch_size=bsz, + src_len=k.size(1), + static_kv=static_kv, + ) + ) + + saved_state["prev_key"] = k.view( + bsz, self.num_heads_partition, -1, self.head_dim + ) + saved_state["prev_value"] = v.view( + bsz, self.num_heads_partition, -1, self.head_dim + ) + saved_state["prev_key_padding_mask"] = key_padding_mask + # In this branch incremental_state is never None + assert incremental_state is not None + incremental_state = self._set_input_buffer(incremental_state, saved_state) + assert k is not None + src_len = k.size(1) + + # This is part of a workaround to get around fork/join parallelism + # not supporting Optional types. + if key_padding_mask is not None and key_padding_mask.dim() == 0: + key_padding_mask = None + + if key_padding_mask is not None: + assert key_padding_mask.size(0) == bsz + assert key_padding_mask.size(1) == src_len + + attn_weights = torch.bmm(q, k.transpose(1, 2)) + + assert list(attn_weights.size()) == [ + bsz * self.num_heads_partition, + tgt_len, + src_len, + ] + + if attn_mask is not None: + attn_mask = attn_mask.unsqueeze(0) + attn_weights += attn_mask + + if key_padding_mask is not None: + # don't attend to padding symbols + attn_weights = attn_weights.view( + bsz, self.num_heads_partition, tgt_len, src_len + ) + if not is_tpu: + attn_weights = attn_weights.masked_fill( + key_padding_mask.unsqueeze(1).unsqueeze(2).to(torch.bool), + float("-inf"), + ) + else: + attn_weights = attn_weights.transpose(0, 2) + attn_weights = attn_weights.masked_fill(key_padding_mask, float("-inf")) + attn_weights = attn_weights.transpose(0, 2) + attn_weights = attn_weights.view( + bsz * self.num_heads_partition, tgt_len, src_len + ) + + attn_weights_float = utils.softmax(attn_weights, dim=-1) + attn_weights = attn_weights_float.type_as(attn_weights) + + with get_cuda_rng_tracker().fork(): + attn_probs = self.dropout_module(attn_weights) + + assert v is not None + attn = torch.bmm(attn_probs, v) + assert list(attn.size()) == [ + bsz * self.num_heads_partition, + tgt_len, + self.head_dim, + ] + embed_dim_partition = embed_dim // self.model_parallel_size + attn = attn.transpose(0, 1).contiguous().view(tgt_len, bsz, embed_dim_partition) + attn = self.out_proj(attn) + # return attn_weights None to keep the return type same as single gpu multihead attention + # This will be deprecated. + attn_weights: Optional[Tensor] = None + + return attn, attn_weights + + @staticmethod + def _append_prev_key_padding_mask( + key_padding_mask: Optional[Tensor], + prev_key_padding_mask: Optional[Tensor], + batch_size: int, + src_len: int, + static_kv: bool, + ) -> Optional[Tensor]: + # saved key padding masks have shape (bsz, seq_len) + if prev_key_padding_mask is not None and static_kv: + new_key_padding_mask = prev_key_padding_mask + elif prev_key_padding_mask is not None and key_padding_mask is not None: + new_key_padding_mask = torch.cat( + [prev_key_padding_mask.float(), key_padding_mask.float()], dim=1 + ) + # During incremental decoding, as the padding token enters and + # leaves the frame, there will be a time when prev or current + # is None + elif prev_key_padding_mask is not None: + + filler = torch.zeros(batch_size, src_len - prev_key_padding_mask.size(1)) + if prev_key_padding_mask.is_cuda: + filler = filler.cuda() + new_key_padding_mask = torch.cat( + [prev_key_padding_mask.float(), filler.float()], dim=1 + ) + elif key_padding_mask is not None: + filler = torch.zeros(batch_size, src_len - key_padding_mask.size(1)) + if key_padding_mask.is_cuda: + filler = filler.cuda() + new_key_padding_mask = torch.cat( + [filler.float(), key_padding_mask.float()], dim=1 + ) + else: + new_key_padding_mask = prev_key_padding_mask + return new_key_padding_mask + + def reorder_incremental_state( + self, incremental_state: Dict[str, Dict[str, Optional[Tensor]]], new_order + ): + """Reorder buffered internal state (for incremental generation).""" + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is not None: + for k in input_buffer.keys(): + if input_buffer[k] is not None: + input_buffer[k] = input_buffer[k].index_select(0, new_order) + incremental_state = self._set_input_buffer(incremental_state, input_buffer) + return incremental_state + + def _get_input_buffer( + self, incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] + ) -> Dict[str, Optional[Tensor]]: + result = self.get_incremental_state(incremental_state, "attn_state") + if result is not None: + return result + else: + empty_result: Dict[str, Optional[Tensor]] = {} + return empty_result + + def _set_input_buffer( + self, + incremental_state: Dict[str, Dict[str, Optional[Tensor]]], + buffer: Dict[str, Optional[Tensor]], + ): + return self.set_incremental_state(incremental_state, "attn_state", buffer) diff --git a/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/transformer_layer.py b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/transformer_layer.py new file mode 100644 index 00000000..7ab53c6e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/model_parallel/modules/transformer_layer.py @@ -0,0 +1,78 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.model_parallel.modules import ModelParallelMultiheadAttention +from fairseq.modules import TransformerDecoderLayer, TransformerEncoderLayer + + +try: + from fairseq.model_parallel.megatron.mpu import ( + ColumnParallelLinear, + RowParallelLinear, + ) + + has_megatron_submodule = True +except (ImportError, ModuleNotFoundError): + has_megatron_submodule = False + + +class ModelParallelTransformerEncoderLayer(TransformerEncoderLayer): + """Encoder layer block over multiple gpus. + + See "Megatron-LM: https://arxiv.org/pdf/1909.08053.pdf" for more details. + """ + + def build_fc1(self, input_dim, output_dim, q_noise, qn_block_size): + if q_noise > 0: + raise NotImplementedError + return ColumnParallelLinear(input_dim, output_dim, gather_output=False) + + def build_fc2(self, input_dim, output_dim, q_noise, qn_block_size): + if q_noise > 0: + raise NotImplementedError + return RowParallelLinear(input_dim, output_dim, input_is_parallel=True) + + def build_self_attention(self, embed_dim, args, **unused_kwargs): + return ModelParallelMultiheadAttention( + embed_dim, + args.encoder_attention_heads, + dropout=args.attention_dropout, + self_attention=True, + ) + + +class ModelParallelTransformerDecoderLayer(TransformerDecoderLayer): + """Decoder layer block. + + See "Megatron-LM: https://arxiv.org/pdf/1909.08053.pdf" for more details. + """ + + def build_fc1(self, input_dim, output_dim, q_noise, qn_block_size): + if q_noise > 0: + raise NotImplementedError + return ColumnParallelLinear(input_dim, output_dim, gather_output=False) + + def build_fc2(self, input_dim, output_dim, q_noise, qn_block_size): + if q_noise > 0: + raise NotImplementedError + return RowParallelLinear(input_dim, output_dim, input_is_parallel=True) + + def build_self_attention(self, embed_dim, args, **unused_kwargs): + return ModelParallelMultiheadAttention( + embed_dim=embed_dim, + num_heads=args.decoder_attention_heads, + dropout=args.attention_dropout, + self_attention=not getattr(args, "cross_self_attention", False), + ) + + def build_encoder_attention(self, embed_dim, args, **unused_kwargs): + return ModelParallelMultiheadAttention( + embed_dim=embed_dim, + num_heads=args.decoder_attention_heads, + kdim=getattr(args, "encoder_embed_dim", None), + vdim=getattr(args, "encoder_embed_dim", None), + dropout=args.attention_dropout, + encoder_decoder_attention=True, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/__init__.py new file mode 100644 index 00000000..616e3051 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/__init__.py @@ -0,0 +1,235 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +import argparse +import importlib +import os + +from contextlib import ExitStack + +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.utils import merge_with_parent +from hydra.core.config_store import ConfigStore +from omegaconf import open_dict, OmegaConf + +from .composite_encoder import CompositeEncoder +from .distributed_fairseq_model import DistributedFairseqModel +from .fairseq_decoder import FairseqDecoder +from .fairseq_encoder import FairseqEncoder +from .fairseq_incremental_decoder import FairseqIncrementalDecoder +from .fairseq_model import ( + BaseFairseqModel, + FairseqEncoderDecoderModel, + FairseqEncoderModel, + FairseqLanguageModel, + FairseqModel, + FairseqMultiModel, +) + + +MODEL_REGISTRY = {} +MODEL_DATACLASS_REGISTRY = {} +ARCH_MODEL_REGISTRY = {} +ARCH_MODEL_NAME_REGISTRY = {} +ARCH_MODEL_INV_REGISTRY = {} +ARCH_CONFIG_REGISTRY = {} + + +__all__ = [ + "BaseFairseqModel", + "CompositeEncoder", + "DistributedFairseqModel", + "FairseqDecoder", + "FairseqEncoder", + "FairseqEncoderDecoderModel", + "FairseqEncoderModel", + "FairseqIncrementalDecoder", + "FairseqLanguageModel", + "FairseqModel", + "FairseqMultiModel", +] + + +def build_model(cfg: FairseqDataclass, task, from_checkpoint=False): + + model = None + model_type = getattr(cfg, "_name", None) or getattr(cfg, "arch", None) + + if not model_type and len(cfg) == 1: + # this is hit if config object is nested in directory that is named after model type + + model_type = next(iter(cfg)) + if model_type in MODEL_DATACLASS_REGISTRY: + cfg = cfg[model_type] + else: + raise Exception( + "Could not infer model type from directory. Please add _name field to indicate model type. " + "Available models: " + + str(MODEL_DATACLASS_REGISTRY.keys()) + + " Requested model type: " + + model_type + ) + + if model_type in ARCH_MODEL_REGISTRY: + # case 1: legacy models + model = ARCH_MODEL_REGISTRY[model_type] + elif model_type in MODEL_DATACLASS_REGISTRY: + # case 2: config-driven models + model = MODEL_REGISTRY[model_type] + + if model_type in MODEL_DATACLASS_REGISTRY: + # set defaults from dataclass. note that arch name and model name can be the same + dc = MODEL_DATACLASS_REGISTRY[model_type] + + if isinstance(cfg, argparse.Namespace): + cfg = dc.from_namespace(cfg) + else: + cfg = merge_with_parent(dc(), cfg, from_checkpoint) + else: + if model_type in ARCH_CONFIG_REGISTRY: + with open_dict(cfg) if OmegaConf.is_config(cfg) else ExitStack(): + # this calls the different "arch" functions (like base_architecture()) that you indicate + # if you specify --arch on the command line. this is only applicable to the old argparse based models + # hydra models should expose different architectures via different config files + # it will modify the cfg object and default parameters according to the arch + ARCH_CONFIG_REGISTRY[model_type](cfg) + + assert model is not None, ( + f"Could not infer model type from {cfg}. " + "Available models: {}".format(MODEL_DATACLASS_REGISTRY.keys()) + + f" Requested model type: {model_type}" + ) + + return model.build_model(cfg, task) + + +def register_model(name, dataclass=None): + """ + New model types can be added to fairseq with the :func:`register_model` + function decorator. + + For example:: + + @register_model('lstm') + class LSTM(FairseqEncoderDecoderModel): + (...) + + .. note:: All models must implement the :class:`BaseFairseqModel` interface. + Typically you will extend :class:`FairseqEncoderDecoderModel` for + sequence-to-sequence tasks or :class:`FairseqLanguageModel` for + language modeling tasks. + + Args: + name (str): the name of the model + """ + + def register_model_cls(cls): + if name in MODEL_REGISTRY: + raise ValueError("Cannot register duplicate model ({})".format(name)) + if not issubclass(cls, BaseFairseqModel): + raise ValueError( + "Model ({}: {}) must extend BaseFairseqModel".format(name, cls.__name__) + ) + MODEL_REGISTRY[name] = cls + if dataclass is not None and not issubclass(dataclass, FairseqDataclass): + raise ValueError( + "Dataclass {} must extend FairseqDataclass".format(dataclass) + ) + + cls.__dataclass = dataclass + if dataclass is not None: + MODEL_DATACLASS_REGISTRY[name] = dataclass + + cs = ConfigStore.instance() + node = dataclass() + node._name = name + cs.store(name=name, group="model", node=node, provider="fairseq") + + @register_model_architecture(name, name) + def noop(_): + pass + + return cls + + return register_model_cls + + +def register_model_architecture(model_name, arch_name): + """ + New model architectures can be added to fairseq with the + :func:`register_model_architecture` function decorator. After registration, + model architectures can be selected with the ``--arch`` command-line + argument. + + For example:: + + @register_model_architecture('lstm', 'lstm_luong_wmt_en_de') + def lstm_luong_wmt_en_de(cfg): + args.encoder_embed_dim = getattr(cfg.model, 'encoder_embed_dim', 1000) + (...) + + The decorated function should take a single argument *cfg*, which is a + :class:`omegaconf.DictConfig`. The decorated function should modify these + arguments in-place to match the desired architecture. + + Args: + model_name (str): the name of the Model (Model must already be + registered) + arch_name (str): the name of the model architecture (``--arch``) + """ + + def register_model_arch_fn(fn): + if model_name not in MODEL_REGISTRY: + raise ValueError( + "Cannot register model architecture for unknown model type ({})".format( + model_name + ) + ) + if arch_name in ARCH_MODEL_REGISTRY: + raise ValueError( + "Cannot register duplicate model architecture ({})".format(arch_name) + ) + if not callable(fn): + raise ValueError( + "Model architecture must be callable ({})".format(arch_name) + ) + ARCH_MODEL_REGISTRY[arch_name] = MODEL_REGISTRY[model_name] + ARCH_MODEL_NAME_REGISTRY[arch_name] = model_name + ARCH_MODEL_INV_REGISTRY.setdefault(model_name, []).append(arch_name) + ARCH_CONFIG_REGISTRY[arch_name] = fn + return fn + + return register_model_arch_fn + + +def import_models(models_dir, namespace): + for file in os.listdir(models_dir): + path = os.path.join(models_dir, file) + if ( + not file.startswith("_") + and not file.startswith(".") + and (file.endswith(".py") or os.path.isdir(path)) + ): + model_name = file[: file.find(".py")] if file.endswith(".py") else file + importlib.import_module(namespace + "." + model_name) + + # extra `model_parser` for sphinx + if model_name in MODEL_REGISTRY: + parser = argparse.ArgumentParser(add_help=False) + group_archs = parser.add_argument_group("Named architectures") + group_archs.add_argument( + "--arch", choices=ARCH_MODEL_INV_REGISTRY[model_name] + ) + group_args = parser.add_argument_group( + "Additional command-line arguments" + ) + MODEL_REGISTRY[model_name].add_args(group_args) + globals()[model_name + "_parser"] = parser + + +# automatically import any Python files in the models/ directory +models_dir = os.path.dirname(__file__) +import_models(models_dir, "fairseq.models") diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/bart/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/bart/__init__.py new file mode 100644 index 00000000..a701923f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/bart/__init__.py @@ -0,0 +1,7 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .hub_interface import * # noqa +from .model import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/bart/hub_interface.py b/PyTorch/NLP/new-Transformer/fairseq/models/bart/hub_interface.py new file mode 100644 index 00000000..6b647c96 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/bart/hub_interface.py @@ -0,0 +1,211 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import copy +import logging +from typing import Dict, List + +import numpy as np +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.data import encoders +from fairseq.hub_utils import GeneratorHubInterface +from omegaconf import open_dict + + +logger = logging.getLogger(__name__) + + +class BARTHubInterface(GeneratorHubInterface): + """A simple PyTorch Hub interface to BART. + + Usage: https://github.com/pytorch/fairseq/tree/main/examples/bart + """ + + def __init__(self, cfg, task, model): + super().__init__(cfg, task, [model]) + self.model = self.models[0] + + def encode( + self, sentence: str, *addl_sentences, no_separator=True + ) -> torch.LongTensor: + """ + BPE-encode a sentence (or multiple sentences). + + Every sequence begins with a beginning-of-sentence (``) symbol. + Every sentence ends with an end-of-sentence (``). + + Example (single sentence): ` a b c ` + Example (sentence pair): ` d e f 1 2 3 ` + + The BPE encoding follows GPT-2. One subtle detail is that the GPT-2 BPE + requires leading spaces. For example:: + + >>> bart.encode('Hello world').tolist() + [0, 31414, 232, 2] + >>> bart.encode(' world').tolist() + [0, 232, 2] + >>> bart.encode('world').tolist() + [0, 8331, 2] + """ + tokens = self.bpe.encode(sentence) + if len(tokens.split(" ")) > min(self.max_positions) - 2: + tokens = " ".join(tokens.split(" ")[: min(self.max_positions) - 2]) + bpe_sentence = " " + tokens + " " + for s in addl_sentences: + bpe_sentence += " " if not no_separator else "" + bpe_sentence += " " + self.bpe.encode(s) + " " + tokens = self.task.source_dictionary.encode_line(bpe_sentence, append_eos=False) + return tokens.long() + + def decode(self, tokens: torch.LongTensor): + assert tokens.dim() == 1 + tokens = tokens.cpu().numpy() + if tokens[0] == self.task.source_dictionary.bos(): + tokens = tokens[1:] # remove + eos_mask = tokens == self.task.source_dictionary.eos() + doc_mask = eos_mask[1:] & eos_mask[:-1] + sentences = np.split(tokens, doc_mask.nonzero()[0] + 1) + sentences = [ + self.bpe.decode(self.task.source_dictionary.string(s)) for s in sentences + ] + if len(sentences) == 1: + return sentences[0] + return sentences + + def _build_sample(self, src_tokens: List[torch.LongTensor]): + # assert torch.is_tensor(src_tokens) + dataset = self.task.build_dataset_for_inference( + src_tokens, + [x.numel() for x in src_tokens], + ) + sample = dataset.collater(dataset) + sample = utils.apply_to_sample(lambda tensor: tensor.to(self.device), sample) + return sample + + def generate( + self, + tokenized_sentences: List[torch.LongTensor], + *args, + inference_step_args=None, + skip_invalid_size_inputs=False, + **kwargs + ) -> List[List[Dict[str, torch.Tensor]]]: + inference_step_args = inference_step_args or {} + if "prefix_tokens" in inference_step_args: + raise NotImplementedError("prefix generation not implemented for BART") + res = [] + for batch in self._build_batches(tokenized_sentences, skip_invalid_size_inputs): + src_tokens = batch["net_input"]["src_tokens"] + inference_step_args["prefix_tokens"] = src_tokens.new_full( + (src_tokens.size(0), 1), fill_value=self.task.source_dictionary.bos() + ).to(device=self.device) + results = super().generate( + src_tokens, + *args, + inference_step_args=inference_step_args, + skip_invalid_size_inputs=skip_invalid_size_inputs, + **kwargs + ) + for id, hypos in zip(batch["id"].tolist(), results): + res.append((id, hypos)) + res = [hypos for _, hypos in sorted(res, key=lambda x: x[0])] + return res + + def extract_features( + self, tokens: torch.LongTensor, return_all_hiddens: bool = False + ) -> torch.Tensor: + if tokens.dim() == 1: + tokens = tokens.unsqueeze(0) + if tokens.size(-1) > min(self.model.max_positions()): + raise ValueError( + "tokens exceeds maximum length: {} > {}".format( + tokens.size(-1), self.model.max_positions() + ) + ) + tokens.to(device=self.device), + prev_output_tokens = tokens.clone() + + prev_output_tokens[:, 0] = tokens.gather( + 1, + (tokens.ne(self.task.source_dictionary.pad()).sum(dim=1) - 1).unsqueeze(-1), + ).squeeze() + + prev_output_tokens[:, 1:] = tokens[:, :-1] + features, extra = self.model( + src_tokens=tokens, + src_lengths=None, + prev_output_tokens=prev_output_tokens, + features_only=True, + return_all_hiddens=return_all_hiddens, + ) + if return_all_hiddens: + # convert from T x B x C -> B x T x C + inner_states = extra["inner_states"] + return [inner_state.transpose(0, 1) for inner_state in inner_states] + else: + return features # just the last layer's features + + def register_classification_head( + self, name: str, num_classes: int = None, embedding_size: int = None, **kwargs + ): + self.model.register_classification_head( + name, num_classes=num_classes, embedding_size=embedding_size, **kwargs + ) + + def predict(self, head: str, tokens: torch.LongTensor, return_logits: bool = False): + if tokens.dim() == 1: + tokens = tokens.unsqueeze(0) + features = self.extract_features(tokens.to(device=self.device)) + sentence_representation = features[ + tokens.eq(self.task.source_dictionary.eos()), : + ].view(features.size(0), -1, features.size(-1))[:, -1, :] + + logits = self.model.classification_heads[head](sentence_representation) + if return_logits: + return logits + return F.log_softmax(logits, dim=-1) + + def fill_mask( + self, + masked_inputs: List[str], + topk: int = 5, + match_source_len: bool = True, + **generate_kwargs + ): + masked_token = "" + batch_tokens = [] + for masked_input in masked_inputs: + assert ( + masked_token in masked_input + ), "please add one {} token for the input".format(masked_token) + + text_spans = masked_input.split(masked_token) + text_spans_bpe = ( + (" {0} ".format(masked_token)) + .join([self.bpe.encode(text_span.rstrip()) for text_span in text_spans]) + .strip() + ) + tokens = self.task.source_dictionary.encode_line( + " " + text_spans_bpe + " ", + append_eos=False, + add_if_not_exist=False, + ).long() + batch_tokens.append(tokens) + + # ensure beam size is at least as big as topk + generate_kwargs["beam"] = max( + topk, + generate_kwargs.get("beam", -1), + ) + generate_kwargs["match_source_len"] = match_source_len + batch_hypos = self.generate(batch_tokens, **generate_kwargs) + + return [ + [(self.decode(hypo["tokens"]), hypo["score"]) for hypo in hypos[:topk]] + for hypos in batch_hypos + ] diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/bart/model.py b/PyTorch/NLP/new-Transformer/fairseq/models/bart/model.py new file mode 100644 index 00000000..e3670c0a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/bart/model.py @@ -0,0 +1,394 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +BART: Denoising Sequence-to-Sequence Pre-training for +Natural Language Generation, Translation, and Comprehension +""" +import logging +from typing import Optional + +import torch +import torch.nn as nn + +from fairseq import utils +from fairseq.models import register_model, register_model_architecture +from fairseq.models.transformer import TransformerModel +from fairseq.modules.transformer_sentence_encoder import init_bert_params + +from .hub_interface import BARTHubInterface + +logger = logging.getLogger(__name__) + + +@register_model("bart") +class BARTModel(TransformerModel): + __jit_unused_properties__ = ["supported_targets"] + + @classmethod + def hub_models(cls): + return { + "bart.base": "http://dl.fbaipublicfiles.com/fairseq/models/bart.base.tar.gz", + "bart.large": "http://dl.fbaipublicfiles.com/fairseq/models/bart.large.tar.gz", + "bart.large.mnli": "http://dl.fbaipublicfiles.com/fairseq/models/bart.large.mnli.tar.gz", + "bart.large.cnn": "http://dl.fbaipublicfiles.com/fairseq/models/bart.large.cnn.tar.gz", + "bart.large.xsum": "http://dl.fbaipublicfiles.com/fairseq/models/bart.large.xsum.tar.gz", + } + + def __init__(self, args, encoder, decoder): + super().__init__(args, encoder, decoder) + + # We follow BERT's random weight initialization + self.apply(init_bert_params) + + self.classification_heads = nn.ModuleDict() + if hasattr(self.encoder, "dictionary"): + self.eos: int = self.encoder.dictionary.eos() + + @staticmethod + def add_args(parser): + super(BARTModel, BARTModel).add_args(parser) + parser.add_argument( + "--pooler-dropout", + type=float, + metavar="D", + help="dropout probability in the masked_lm pooler layers", + ) + parser.add_argument( + "--pooler-activation-fn", + choices=utils.get_available_activation_fns(), + help="activation function to use for pooler layer", + ) + parser.add_argument( + "--spectral-norm-classification-head", + action="store_true", + help="Apply spectral normalization on the classification head", + ) + + @property + def supported_targets(self): + return {"self"} + + def forward( + self, + src_tokens, + src_lengths, + prev_output_tokens, + features_only: bool = False, + classification_head_name: Optional[str] = None, + token_embeddings: Optional[torch.Tensor] = None, + return_all_hiddens: bool = True, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + ): + if classification_head_name is not None: + features_only = True + + encoder_out = self.encoder( + src_tokens, + src_lengths=src_lengths, + token_embeddings=token_embeddings, + return_all_hiddens=return_all_hiddens, + ) + x, extra = self.decoder( + prev_output_tokens, + encoder_out=encoder_out, + features_only=features_only, + alignment_layer=alignment_layer, + alignment_heads=alignment_heads, + src_lengths=src_lengths, + return_all_hiddens=return_all_hiddens, + ) + eos: int = self.eos + if classification_head_name is not None: + sentence_representation = x[src_tokens.eq(eos), :].view( + x.size(0), -1, x.size(-1) + )[:, -1, :] + for k, head in self.classification_heads.items(): + # for torch script only supports iteration + if k == classification_head_name: + x = head(sentence_representation) + break + return x, extra + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + bpe="gpt2", + sample_break_mode="eos", + **kwargs, + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + bpe=bpe, + load_checkpoint_heads=True, + sample_break_mode=sample_break_mode, + **kwargs, + ) + return BARTHubInterface(x["args"], x["task"], x["models"][0]) + + def register_classification_head( + self, name, num_classes=None, inner_dim=None, **kwargs + ): + """Register a classification head.""" + logger.info("Registering classification head: {0}".format(name)) + if name in self.classification_heads: + prev_num_classes = self.classification_heads[name].out_proj.out_features + prev_inner_dim = self.classification_heads[name].dense.out_features + if num_classes != prev_num_classes or inner_dim != prev_inner_dim: + logger.warning( + 're-registering head "{}" with num_classes {} (prev: {}) ' + "and inner_dim {} (prev: {})".format( + name, num_classes, prev_num_classes, inner_dim, prev_inner_dim + ) + ) + self.classification_heads[name] = BARTClassificationHead( + input_dim=self.args.encoder_embed_dim, + inner_dim=inner_dim or self.args.encoder_embed_dim, + num_classes=num_classes, + activation_fn=self.args.pooler_activation_fn, + pooler_dropout=self.args.pooler_dropout, + do_spectral_norm=getattr( + self.args, "spectral_norm_classification_head", False + ), + ) + + def upgrade_state_dict_named(self, state_dict, name): + super().upgrade_state_dict_named(state_dict, name) + + prefix = name + "." if name != "" else "" + current_head_names = ( + [] + if not hasattr(self, "classification_heads") + else self.classification_heads.keys() + ) + + # Handle new classification heads present in the state dict. + keys_to_delete = [] + for k in state_dict.keys(): + if not k.startswith(prefix + "classification_heads."): + continue + + head_name = k[len(prefix + "classification_heads.") :].split(".")[0] + num_classes = state_dict[ + prefix + "classification_heads." + head_name + ".out_proj.weight" + ].size(0) + inner_dim = state_dict[ + prefix + "classification_heads." + head_name + ".dense.weight" + ].size(0) + + if getattr(self.args, "load_checkpoint_heads", False): + if head_name not in current_head_names: + self.register_classification_head(head_name, num_classes, inner_dim) + else: + if head_name not in current_head_names: + logger.warning( + "deleting classification head ({}) from checkpoint " + "not present in current model: {}".format(head_name, k) + ) + keys_to_delete.append(k) + elif ( + num_classes + != self.classification_heads[head_name].out_proj.out_features + or inner_dim + != self.classification_heads[head_name].dense.out_features + ): + logger.warning( + "deleting classification head ({}) from checkpoint " + "with different dimensions than current model: {}".format( + head_name, k + ) + ) + keys_to_delete.append(k) + for k in keys_to_delete: + del state_dict[k] + + def truncate_emb(key): + if key in state_dict: + state_dict[key] = state_dict[key][:-1, :] + + # When finetuning on translation task, remove last row of + # embedding matrix that corresponds to mask_idx token. + loaded_dict_size = state_dict["encoder.embed_tokens.weight"].size(0) + if ( + loaded_dict_size == len(self.encoder.dictionary) + 1 + and "" not in self.encoder.dictionary + ): + truncate_emb("encoder.embed_tokens.weight") + truncate_emb("decoder.embed_tokens.weight") + truncate_emb("encoder.output_projection.weight") + truncate_emb("decoder.output_projection.weight") + + # When continued pretraining on new set of languages for mbart, + # add extra lang embeddings at the end of embed_tokens. + # Note: newly added languages are assumed to have been added at the end. + if self.args.task == "multilingual_denoising" and loaded_dict_size < len( + self.encoder.dictionary + ): + logger.info( + "Adding extra language embeddings not found in pretrained model for " + "continued pretraining of MBART on new set of languages." + ) + loaded_mask_token_embedding = state_dict["encoder.embed_tokens.weight"][ + -1, : + ] + + num_langids_to_add = len(self.encoder.dictionary) - loaded_dict_size + embed_dim = state_dict["encoder.embed_tokens.weight"].size(1) + + new_lang_embed_to_add = torch.zeros(num_langids_to_add, embed_dim) + nn.init.normal_(new_lang_embed_to_add, mean=0, std=embed_dim**-0.5) + new_lang_embed_to_add = new_lang_embed_to_add.to( + dtype=state_dict["encoder.embed_tokens.weight"].dtype, + ) + + state_dict["encoder.embed_tokens.weight"] = torch.cat( + [ + state_dict["encoder.embed_tokens.weight"][ + : loaded_dict_size - 1, : + ], + new_lang_embed_to_add, + loaded_mask_token_embedding.unsqueeze(0), + ] + ) + state_dict["decoder.embed_tokens.weight"] = torch.cat( + [ + state_dict["decoder.embed_tokens.weight"][ + : loaded_dict_size - 1, : + ], + new_lang_embed_to_add, + loaded_mask_token_embedding.unsqueeze(0), + ] + ) + + # Copy any newly-added classification heads into the state dict + # with their current weights. + if hasattr(self, "classification_heads"): + cur_state = self.classification_heads.state_dict() + for k, v in cur_state.items(): + if prefix + "classification_heads." + k not in state_dict: + logger.info("Overwriting " + prefix + "classification_heads." + k) + state_dict[prefix + "classification_heads." + k] = v + + def set_beam_size(self, beam): + """Set beam size for efficient beamable enc-dec attention.""" + beamable = False + for layer in self.decoder.layers: + if layer.encoder_attn is not None: + if hasattr(layer.encoder_attn, "set_beam_size"): + layer.encoder_attn.set_beam_size(beam) + beamable = True + if beamable: + self.encoder.reorder_encoder_out = self.encoder._reorder_encoder_out + + +class BARTClassificationHead(nn.Module): + """Head for sentence-level classification tasks.""" + + def __init__( + self, + input_dim, + inner_dim, + num_classes, + activation_fn, + pooler_dropout, + do_spectral_norm=False, + ): + super().__init__() + self.dense = nn.Linear(input_dim, inner_dim) + self.activation_fn = utils.get_activation_fn(activation_fn) + self.dropout = nn.Dropout(p=pooler_dropout) + self.out_proj = nn.Linear(inner_dim, num_classes) + + if do_spectral_norm: + self.out_proj = torch.nn.utils.spectral_norm(self.out_proj) + + def forward(self, features, **kwargs): + x = features + x = self.dropout(x) + x = self.dense(x) + x = self.activation_fn(x) + x = self.dropout(x) + x = self.out_proj(x) + return x + + +@register_model_architecture("bart", "bart_large") +def bart_large_architecture(args): + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4 * 1024) + args.encoder_layers = getattr(args, "encoder_layers", 12) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 16) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", True) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 12) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 16) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", True) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.relu_dropout = getattr(args, "relu_dropout", 0.0) + args.dropout = getattr(args, "dropout", 0.1) + args.max_target_positions = getattr(args, "max_target_positions", 1024) + args.max_source_positions = getattr(args, "max_source_positions", 1024) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", True + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", True) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + args.no_scale_embedding = getattr(args, "no_scale_embedding", True) + args.layernorm_embedding = getattr(args, "layernorm_embedding", True) + + args.activation_fn = getattr(args, "activation_fn", "gelu") + args.pooler_activation_fn = getattr(args, "pooler_activation_fn", "tanh") + args.pooler_dropout = getattr(args, "pooler_dropout", 0.0) + + +@register_model_architecture("bart", "bart_base") +def bart_base_architecture(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 768) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4 * 768) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 12) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 12) + bart_large_architecture(args) + + +@register_model_architecture("bart", "mbart_large") +def mbart_large_architecture(args): + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + bart_large_architecture(args) + + +@register_model_architecture("bart", "mbart_base") +def mbart_base_architecture(args): + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + bart_base_architecture(args) + + +@register_model_architecture("bart", "mbart_base_wmt20") +def mbart_base_wmt20_architecture(args): + args.layernorm_embedding = getattr(args, "layernorm_embedding", False) + mbart_base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/composite_encoder.py b/PyTorch/NLP/new-Transformer/fairseq/models/composite_encoder.py new file mode 100644 index 00000000..4e20fe3a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/composite_encoder.py @@ -0,0 +1,57 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .fairseq_encoder import FairseqEncoder + + +class CompositeEncoder(FairseqEncoder): + """ + A wrapper around a dictionary of :class:`FairseqEncoder` objects. + + We run forward on each encoder and return a dictionary of outputs. The first + encoder's dictionary is used for initialization. + + Args: + encoders (dict): a dictionary of :class:`FairseqEncoder` objects. + """ + + def __init__(self, encoders): + super().__init__(next(iter(encoders.values())).dictionary) + self.encoders = encoders + for key in self.encoders: + self.add_module(key, self.encoders[key]) + + def forward(self, src_tokens, src_lengths): + """ + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (LongTensor): lengths of each source sentence of shape + `(batch)` + + Returns: + dict: + the outputs from each Encoder + """ + encoder_out = {} + for key in self.encoders: + encoder_out[key] = self.encoders[key](src_tokens, src_lengths) + return encoder_out + + def reorder_encoder_out(self, encoder_out, new_order): + """Reorder encoder output according to new_order.""" + for key in self.encoders: + encoder_out[key] = self.encoders[key].reorder_encoder_out( + encoder_out[key], new_order + ) + return encoder_out + + def max_positions(self): + return min(self.encoders[key].max_positions() for key in self.encoders) + + def upgrade_state_dict(self, state_dict): + for key in self.encoders: + self.encoders[key].upgrade_state_dict(state_dict) + return state_dict diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/distributed_fairseq_model.py b/PyTorch/NLP/new-Transformer/fairseq/models/distributed_fairseq_model.py new file mode 100644 index 00000000..fd76bcd4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/distributed_fairseq_model.py @@ -0,0 +1,147 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +import signal +import threading + +import torch +import torch.nn as nn +from torch.nn.parallel import DistributedDataParallel + +from fairseq.distributed import ( + DistributedTimeoutWrapper, + LegacyDistributedDataParallel, + ModuleProxyWrapper, + TPUDistributedDataParallel, +) + +logger = logging.getLogger(__name__) + + +_SLOWMO_DDP_DISABLED = False +try: + from fairscale.experimental.nn.data_parallel import ( + SlowMoBaseAlgorithm, + SlowMoDistributedDataParallel, + ) +except ImportError: + _SLOWMO_DDP_DISABLED = True + + +def DistributedFairseqModel(args, model, process_group, device): + """ + Wrap a *model* to support distributed data parallel training. + + This is similar to the built-in DistributedDataParallel, but allows + additional configuration of the DistributedDataParallel class to + use, and also provides easier access to the wrapped model by + forwarding requests for missing attributes to the wrapped model. + + Args: + args (argparse.Namespace): fairseq args + model (BaseFairseqModel): model to wrap + process_group: the c10d process group to be used for distributed data + parallel all-reduction. + device: device to move model to + """ + assert isinstance(model, nn.Module) + if args.tpu: + wrapped_model = TPUDistributedDataParallel( + module=model.to(device), + process_group=process_group, + ) + # forward missing getattr and state_dict/load_state_dict to orig model + wrapped_model = ModuleProxyWrapper(wrapped_model) + elif args.ddp_backend in {"c10d", "pytorch_ddp"}: + wrapped_model = DistributedDataParallel( + module=model.to(device), + device_ids=[args.device_id], + output_device=args.device_id, + broadcast_buffers=args.broadcast_buffers, + bucket_cap_mb=args.bucket_cap_mb, + process_group=process_group, + find_unused_parameters=args.find_unused_parameters, + gradient_as_bucket_view=args.gradient_as_bucket_view, + ) + if args.ddp_comm_hook == "fp16": + logger.info("enable fp16 communication hook in DDP") + try: + from torch.distributed.algorithms.ddp_comm_hooks import ( + DDPCommHookType, + register_ddp_comm_hook, + ) + except: + logger.error( + "Could not import from torch.distributed.algorithms.ddp_comm_hooks; you may need to update your pytorch version" + ) + raise + + register_ddp_comm_hook(DDPCommHookType.FP16_COMPRESS, wrapped_model) + # forward missing getattr and state_dict/load_state_dict to orig model + wrapped_model = ModuleProxyWrapper(wrapped_model) + elif args.ddp_backend in {"no_c10d", "legacy_ddp"}: + wrapped_model = LegacyDistributedDataParallel( + module=model.to(device), + buffer_size=2**28, + process_group=process_group, + ) + # forward missing getattr and state_dict/load_state_dict to orig model + wrapped_model = ModuleProxyWrapper(wrapped_model) + elif args.ddp_backend == "slowmo": + if _SLOWMO_DDP_DISABLED: + raise ImportError( + "Cannot find SlowMoDistributedDataParallel. " + "Please install fairscale with: pip install fairscale" + ) + + # The values of slowmo_momentum below were obtained by tuning on the + # En-De 16 dataset by training the transformer_wmt_en_de_large model + if args.slowmo_momentum is None: + if args.distributed_world_size <= 16: + args.slowmo_momentum = 0.0 + elif args.distributed_world_size <= 32: + args.slowmo_momentum = 0.2 + elif args.distributed_world_size <= 64: + args.slowmo_momentum = 0.5 + else: + args.slowmo_momentum = 0.6 + slowmo_base_algorithm = SlowMoBaseAlgorithm[args.slowmo_base_algorithm.upper()] + + wrapped_model = SlowMoDistributedDataParallel( + module=model.to(device), + broadcast_buffers=args.broadcast_buffers, + nprocs_per_node=args.nprocs_per_node, + slowmo_momentum=args.slowmo_momentum, + slowmo_base_algorithm=slowmo_base_algorithm, + localsgd_frequency=args.localsgd_frequency, + ) + # forward missing getattr and state_dict/load_state_dict to orig model + wrapped_model = ModuleProxyWrapper(wrapped_model) + elif args.ddp_backend == "fully_sharded": + try: + from fairscale.nn.data_parallel import FullyShardedDataParallel as FSDP + except ImportError: + raise ImportError( + "Cannot find FullyShardedDataParallel. " + "Please install fairscale with: pip install fairscale" + ) + assert isinstance(model, FSDP), "expected model to already be wrapped in FSDP" + wrapped_model = model + if args.memory_efficient_fp16: + wrapped_model = wrapped_model.half() + if not args.cpu_offload: + wrapped_model = wrapped_model.to(device=device) + else: + raise ValueError("Unknown --ddp-backend: " + args.ddp_backend) + + # kill hung distributed jobs after a timeout + if getattr(args, "heartbeat_timeout", -1) > 0: + wrapped_model = DistributedTimeoutWrapper( + wrapped_model, timeout=getattr(args, "heartbeat_timeout", -1) + ) + + return wrapped_model diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/ema/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/ema/__init__.py new file mode 100644 index 00000000..503ceaa6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/ema/__init__.py @@ -0,0 +1,20 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import importlib +import os + +from .ema import EMA + + +def build_ema(model, cfg, device): + return EMA(model, cfg, device) + + +# automatically import any Python files in the models/ema/ directory +for file in sorted(os.listdir(os.path.dirname(__file__))): + if file.endswith(".py") and not file.startswith("_"): + file_name = file[: file.find(".py")] + importlib.import_module("fairseq.models.ema." + file_name) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/ema/ema.py b/PyTorch/NLP/new-Transformer/fairseq/models/ema/ema.py new file mode 100644 index 00000000..472d5d5f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/ema/ema.py @@ -0,0 +1,209 @@ +#!/usr/bin/env python3 + +""" +This module has the EMA class used to store a copy of the exponentially decayed +model params. + +Typical usage of EMA class involves initializing an object using an existing +model (random or from a seed model) and setting the config like ema_decay, +ema_start_update which determine how the EMA model is updated. After every +update of the model i.e. at the end of the train_step, the EMA should be updated +by passing the new model to the EMA.step function. The EMA model state dict +can be stored in the extra state under the key of "ema" and dumped +into a checkpoint and loaded. The EMA object can be passed to tasks +by setting task.uses_ema property. +EMA is a smoothed/ensemble model which might have better performance +when used for inference or further fine-tuning. EMA class has a +reverse function to load the EMA params into a model and use it +like a regular model. + +This implementation is used for trainer-level ema tracking. For EMA tracking +inside the model, please use fairseq/modules/ema_module.py instead. +""" + +import copy +import logging + +import torch + +from fairseq import checkpoint_utils + + +class EMA(object): + """Exponential Moving Average of Fairseq Models + EMA keeps a copy of the exponentially decayed model params. + The set of params should include both gradient-descent and + non-gradient descent params, such as batch mean/var and buffers. + This is a modified implementation of + the open source code in https://github.com/zhawe01/fairseq-gec.git, + and internal source code in + fbcode/mobile-vision/projects/classification_pytorch/lib/utils/model_ema.py. + + Similar to TF EMA. + https://www.tensorflow.org/api_docs/python/tf/train/ExponentialMovingAverage. + EMA provides a averaged and smoothed set of model weights, and has been shown to + improve vision models. EMA class does all necessary functions to update, reload, + or init EMA methods. + + EMA object is initialized from an arbitrary model. By default, it is stored in + the same device (unless device specified at initialization) and with the + same precision as the model (unless ema_fp32 is True). ema_fp32 is recommended. + This stores the EMA parameters in fp32 only for the EMA update step, and + is used at the default precision otherwise. + EMA is usually enabled using EMAConfig with store_ema=True. Some important + parameters to configure EMA are + 1) ema_decay - The decay of EMA + 2) ema_update_freq - EMA is updated every this many model updates. + 3) ema_start_update - Start EMA update after this many model updates [default 0] + + Key methods: + 1) step - One update of EMA using new model + 2) restore - Update EMA from a state dict + 3) reverse - Load EMA into a model + 4) get_decay, _set_decay - Used to get or set the decay. Note _set_decay is + called from step. + 5) build_fp32_params - Used to initialize or update the fp32 copy of EMA params. + Note this is enabled only when ema_fp32=True + """ + + def __init__(self, model, config, device=None, skip_keys=None): + """ + @param model model to initialize the EMA with + @param config EMAConfig object with configuration like + ema_decay, ema_update_freq, ema_fp32 + @param device If provided, copy EMA to this device (e.g. gpu). + Otherwise EMA is in the same device as the model. + """ + + self.decay = config.ema_decay + self.model = copy.deepcopy(model) + self.model.requires_grad_(False) + self.config = config + self.skip_keys = skip_keys or set() + self.fp32_params = {} + + if self.config.ema_seed_model is not None: + state = checkpoint_utils.load_ema_from_checkpoint( + self.config.ema_seed_model + ) + self.model.load_state_dict(state["model"], strict=True) + + if device is not None: + logging.info(f"Copying EMA model to device {device}") + self.model = self.model.to(device=device) + + if self.config.ema_fp32: + self.build_fp32_params() + + self.update_freq_counter = 0 + + def get_model(self): + return self.model + + def build_fp32_params(self, state_dict=None): + """ + Store a copy of the EMA params in fp32. + If state dict is passed, the EMA params is copied from + the provided state dict. Otherwise, it is copied from the + current EMA model parameters. + """ + if not self.config.ema_fp32: + raise RuntimeError( + "build_fp32_params should not be called if ema_fp32=False. " + "Use ema_fp32=True if this is really intended." + ) + + if state_dict is None: + state_dict = self.model.state_dict() + + def _to_float(t): + return t.float() if torch.is_floating_point(t) else t + + for param_key in state_dict: + if param_key in self.fp32_params: + self.fp32_params[param_key].copy_(state_dict[param_key]) + else: + self.fp32_params[param_key] = _to_float(state_dict[param_key]) + + def restore(self, state_dict, build_fp32_params=False): + """Load data from a model spec into EMA model""" + self.model.load_state_dict(state_dict, strict=False) + if build_fp32_params: + self.build_fp32_params(state_dict) + + def _set_decay(self, decay): + self.decay = decay + + def get_decay(self): + return self.decay + + def _step_internal(self, new_model, updates=None): + """One update of the EMA model based on new model weights""" + decay = self.decay + + ema_state_dict = {} + ema_params = ( + self.fp32_params if self.config.ema_fp32 else self.model.state_dict() + ) + for key, param in new_model.state_dict().items(): + if isinstance(param, dict): + continue + try: + ema_param = ema_params[key] + except KeyError: + ema_param = ( + param.float().clone() if param.ndim == 1 else copy.deepcopy(param) + ) + + if param.shape != ema_param.shape: + raise ValueError( + "incompatible tensor shapes between model param and ema param" + + "{} vs. {}".format(param.shape, ema_param.shape) + ) + + if "version" in key: + # Do not decay a model.version pytorch param + continue + + if key in self.skip_keys: + ema_param = param.to(dtype=ema_param.dtype).clone() + else: + ema_param.mul_(decay) + ema_param.add_(param.to(dtype=ema_param.dtype), alpha=1 - decay) + ema_state_dict[key] = ema_param + self.restore(ema_state_dict, build_fp32_params=False) + + def step(self, new_model, updates=None): + """ + One update of EMA which is done every self.config.ema_update_freq + updates of the model. + + @param updates The current number of model updates done. + Decay is set of 0 if model updates < ema_start_update, which means + the model will be simply copied over to the EMA. + When model updates >= ema_start_updates, then EMA is updated with + a decay of self.config.ema_decay. + """ + if updates is not None: + self._set_decay( + 0 if updates < self.config.ema_start_update else self.config.ema_decay + ) + if self.config.ema_update_freq > 1: + self.update_freq_counter += 1 + if self.update_freq_counter >= self.config.ema_update_freq: + self._step_internal(new_model, updates) + self.update_freq_counter = 0 + else: + self._step_internal(new_model, updates) + + def reverse(self, model): + """ + Load the model parameters from EMA model. + Useful for inference or fine-tuning from the EMA model. + """ + d = self.model.state_dict() + if "_ema" in d: + del d["_ema"] + + model.load_state_dict(d, strict=False) + return model diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_decoder.py b/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_decoder.py new file mode 100644 index 00000000..13b73d63 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_decoder.py @@ -0,0 +1,104 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Dict, List, Optional, Tuple + +import torch.nn as nn +from fairseq import utils +from torch import Tensor + + +class FairseqDecoder(nn.Module): + """Base class for decoders.""" + + def __init__(self, dictionary): + super().__init__() + self.dictionary = dictionary + self.onnx_trace = False + self.adaptive_softmax = None + + def forward(self, prev_output_tokens, encoder_out=None, **kwargs): + """ + Args: + prev_output_tokens (LongTensor): shifted output tokens of shape + `(batch, tgt_len)`, for teacher forcing + encoder_out (dict, optional): output from the encoder, used for + encoder-side attention + + Returns: + tuple: + - the decoder's output of shape `(batch, tgt_len, vocab)` + - a dictionary with any model-specific outputs + """ + x, extra = self.extract_features( + prev_output_tokens, encoder_out=encoder_out, **kwargs + ) + x = self.output_layer(x) + return x, extra + + def extract_features(self, prev_output_tokens, encoder_out=None, **kwargs): + """ + Returns: + tuple: + - the decoder's features of shape `(batch, tgt_len, embed_dim)` + - a dictionary with any model-specific outputs + """ + raise NotImplementedError + + def output_layer(self, features, **kwargs): + """ + Project features to the default output size, e.g., vocabulary size. + + Args: + features (Tensor): features returned by *extract_features*. + """ + raise NotImplementedError + + def get_normalized_probs( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + log_probs: bool, + sample: Optional[Dict[str, Tensor]] = None, + ): + """Get normalized probabilities (or log probs) from a net's output.""" + return self.get_normalized_probs_scriptable(net_output, log_probs, sample) + + # TorchScript doesn't support super() method so that the scriptable Subclass + # can't access the base class model in Torchscript. + # Current workaround is to add a helper function with different name and + # call the helper function from scriptable Subclass. + def get_normalized_probs_scriptable( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + log_probs: bool, + sample: Optional[Dict[str, Tensor]] = None, + ): + """Get normalized probabilities (or log probs) from a net's output.""" + + if hasattr(self, "adaptive_softmax") and self.adaptive_softmax is not None: + if sample is not None: + assert "target" in sample + target = sample["target"] + else: + target = None + out = self.adaptive_softmax.get_log_prob(net_output[0], target=target) + return out.exp_() if not log_probs else out + + logits = net_output[0] + if log_probs: + return utils.log_softmax(logits, dim=-1, onnx_trace=self.onnx_trace) + else: + return utils.softmax(logits, dim=-1, onnx_trace=self.onnx_trace) + + def max_positions(self): + """Maximum input length supported by the decoder.""" + return 1e6 # an arbitrary large number + + def upgrade_state_dict_named(self, state_dict, name): + """Upgrade old state dicts to work with newer code.""" + return state_dict + + def prepare_for_onnx_export_(self): + self.onnx_trace = True diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_encoder.py b/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_encoder.py new file mode 100644 index 00000000..08cbde15 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_encoder.py @@ -0,0 +1,92 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Dict, List, NamedTuple, Optional + +import torch +import torch.nn as nn +from torch import Tensor + + +EncoderOut = NamedTuple( + "EncoderOut", + [ + ("encoder_out", Tensor), # T x B x C + ("encoder_padding_mask", Optional[Tensor]), # B x T + ("encoder_embedding", Optional[Tensor]), # B x T x C + ("encoder_states", Optional[List[Tensor]]), # List[T x B x C] + ("src_tokens", Optional[Tensor]), # B x T + ("src_lengths", Optional[Tensor]), # B x 1 + ], +) + + +class FairseqEncoder(nn.Module): + """Base class for encoders.""" + + def __init__(self, dictionary): + super().__init__() + self.dictionary = dictionary + + def forward(self, src_tokens, src_lengths=None, **kwargs): + """ + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (LongTensor): lengths of each source sentence of shape + `(batch)` + """ + raise NotImplementedError + + def forward_torchscript(self, net_input: Dict[str, Tensor]): + """A TorchScript-compatible version of forward. + + Encoders which use additional arguments may want to override + this method for TorchScript compatibility. + """ + if torch.jit.is_scripting(): + return self.forward( + src_tokens=net_input["src_tokens"], + src_lengths=net_input["src_lengths"], + ) + else: + return self.forward_non_torchscript(net_input) + + @torch.jit.unused + def forward_non_torchscript(self, net_input: Dict[str, Tensor]): + encoder_input = { + k: v for k, v in net_input.items() if k != "prev_output_tokens" + } + return self.forward(**encoder_input) + + def reorder_encoder_out(self, encoder_out, new_order): + """ + Reorder encoder output according to `new_order`. + + Args: + encoder_out: output from the ``forward()`` method + new_order (LongTensor): desired order + + Returns: + `encoder_out` rearranged according to `new_order` + """ + raise NotImplementedError + + def max_positions(self): + """Maximum input length supported by the encoder.""" + return 1e6 # an arbitrary large number + + def upgrade_state_dict_named(self, state_dict, name): + """Upgrade old state dicts to work with newer code.""" + return state_dict + + def set_num_updates(self, num_updates): + """State from trainer to pass along to model at every update.""" + + def _apply(m): + if hasattr(m, "set_num_updates") and m != self: + m.set_num_updates(num_updates) + + self.apply(_apply) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_incremental_decoder.py b/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_incremental_decoder.py new file mode 100644 index 00000000..cc72a0f8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_incremental_decoder.py @@ -0,0 +1,118 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from typing import Dict, Optional + +from fairseq.incremental_decoding_utils import with_incremental_state +from fairseq.models import FairseqDecoder +from torch import Tensor + + +logger = logging.getLogger(__name__) + + +@with_incremental_state +class FairseqIncrementalDecoder(FairseqDecoder): + """Base class for incremental decoders. + + Incremental decoding is a special mode at inference time where the Model + only receives a single timestep of input corresponding to the previous + output token (for teacher forcing) and must produce the next output + *incrementally*. Thus the model must cache any long-term state that is + needed about the sequence, e.g., hidden states, convolutional states, etc. + + Compared to the standard :class:`FairseqDecoder` interface, the incremental + decoder interface allows :func:`forward` functions to take an extra keyword + argument (*incremental_state*) that can be used to cache state across + time-steps. + + The :class:`FairseqIncrementalDecoder` interface also defines the + :func:`reorder_incremental_state` method, which is used during beam search + to select and reorder the incremental state based on the selection of beams. + + To learn more about how incremental decoding works, refer to `this blog + `_. + """ + + def __init__(self, dictionary): + super().__init__(dictionary) + + def forward( + self, prev_output_tokens, encoder_out=None, incremental_state=None, **kwargs + ): + """ + Args: + prev_output_tokens (LongTensor): shifted output tokens of shape + `(batch, tgt_len)`, for teacher forcing + encoder_out (dict, optional): output from the encoder, used for + encoder-side attention + incremental_state (dict, optional): dictionary used for storing + state during :ref:`Incremental decoding` + + Returns: + tuple: + - the decoder's output of shape `(batch, tgt_len, vocab)` + - a dictionary with any model-specific outputs + """ + raise NotImplementedError + + def extract_features( + self, prev_output_tokens, encoder_out=None, incremental_state=None, **kwargs + ): + """ + Returns: + tuple: + - the decoder's features of shape `(batch, tgt_len, embed_dim)` + - a dictionary with any model-specific outputs + """ + raise NotImplementedError + + def reorder_incremental_state( + self, + incremental_state: Dict[str, Dict[str, Optional[Tensor]]], + new_order: Tensor, + ): + """Reorder incremental state. + + This will be called when the order of the input has changed from the + previous time step. A typical use case is beam search, where the input + order changes between time steps based on the selection of beams. + """ + pass + + def reorder_incremental_state_scripting( + self, + incremental_state: Dict[str, Dict[str, Optional[Tensor]]], + new_order: Tensor, + ): + """Main entry point for reordering the incremental state. + + Due to limitations in TorchScript, we call this function in + :class:`fairseq.sequence_generator.SequenceGenerator` instead of + calling :func:`reorder_incremental_state` directly. + """ + for module in self.modules(): + if hasattr(module, "reorder_incremental_state"): + result = module.reorder_incremental_state(incremental_state, new_order) + if result is not None: + incremental_state = result + + def set_beam_size(self, beam_size): + """Sets the beam size in the decoder and all children.""" + if getattr(self, "_beam_size", -1) != beam_size: + seen = set() + + def apply_set_beam_size(module): + if ( + module != self + and hasattr(module, "set_beam_size") + and module not in seen + ): + seen.add(module) + module.set_beam_size(beam_size) + + self.apply(apply_set_beam_size) + self._beam_size = beam_size diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_model.py b/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_model.py new file mode 100644 index 00000000..42f9134a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/fairseq_model.py @@ -0,0 +1,574 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Base classes for various fairseq models. +""" + +import logging +from argparse import Namespace +from typing import Dict, List, Optional, Tuple + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.data import Dictionary +from fairseq.dataclass.utils import ( + convert_namespace_to_omegaconf, + gen_parser_from_dataclass, +) +from fairseq.models import FairseqDecoder, FairseqEncoder +from omegaconf import DictConfig +from torch import Tensor + + +logger = logging.getLogger(__name__) + + +def check_type(module, expected_type): + if hasattr(module, "unwrapped_module"): + assert isinstance( + module.unwrapped_module, expected_type + ), f"{type(module.unwrapped_module)} != {expected_type}" + else: + assert isinstance(module, expected_type), f"{type(module)} != {expected_type}" + + +class BaseFairseqModel(nn.Module): + """Base class for fairseq models.""" + + def __init__(self): + super().__init__() + self._is_generation_fast = False + + @classmethod + def add_args(cls, parser): + """Add model-specific arguments to the parser.""" + dc = getattr(cls, "__dataclass", None) + if dc is not None: + # do not set defaults so that settings defaults from various architectures still works + gen_parser_from_dataclass(parser, dc(), delete_default=True) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + raise NotImplementedError("Model must implement the build_model method") + + def get_targets(self, sample, net_output): + """Get targets from either the sample or the net's output.""" + return sample["target"] + + def get_normalized_probs( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + log_probs: bool, + sample: Optional[Dict[str, Tensor]] = None, + ): + """Get normalized probabilities (or log probs) from a net's output.""" + return self.get_normalized_probs_scriptable(net_output, log_probs, sample) + + # TorchScript doesn't support super() method so that the scriptable Subclass + # can't access the base class model in Torchscript. + # Current workaround is to add a helper function with different name and + # call the helper function from scriptable Subclass. + def get_normalized_probs_scriptable( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + log_probs: bool, + sample: Optional[Dict[str, Tensor]] = None, + ): + """Scriptable helper function for get_normalized_probs in ~BaseFairseqModel""" + if hasattr(self, "decoder"): + return self.decoder.get_normalized_probs(net_output, log_probs, sample) + elif torch.is_tensor(net_output): + # syntactic sugar for simple models which don't have a decoder + # (e.g., the classification tutorial) + logits = net_output.float() + if log_probs: + return F.log_softmax(logits, dim=-1) + else: + return F.softmax(logits, dim=-1) + raise NotImplementedError + + def extract_features(self, *args, **kwargs): + """Similar to *forward* but only return features.""" + return self(*args, **kwargs) + + def max_positions(self): + """Maximum length supported by the model.""" + return None + + def load_state_dict( + self, + state_dict, + strict=True, + model_cfg: Optional[DictConfig] = None, + args: Optional[Namespace] = None, + ): + """Copies parameters and buffers from *state_dict* into this module and + its descendants. + + Overrides the method in :class:`nn.Module`. Compared with that method + this additionally "upgrades" *state_dicts* from old checkpoints. + """ + + if model_cfg is None and args is not None: + logger.warn( + "using 'args' is deprecated, please update your code to use dataclass config" + ) + model_cfg = convert_namespace_to_omegaconf(args).model + + self.upgrade_state_dict(state_dict) + + from fairseq.checkpoint_utils import prune_state_dict + + new_state_dict = prune_state_dict(state_dict, model_cfg) + return super().load_state_dict(new_state_dict, strict) + + def upgrade_state_dict(self, state_dict): + """Upgrade old state dicts to work with newer code.""" + self.upgrade_state_dict_named(state_dict, "") + + def upgrade_state_dict_named(self, state_dict, name): + """Upgrade old state dicts to work with newer code. + + Args: + state_dict (dict): state dictionary to upgrade, in place + name (str): the state dict key corresponding to the current module + """ + assert state_dict is not None + + def do_upgrade(m, prefix): + if len(prefix) > 0: + prefix += "." + + for n, c in m.named_children(): + name = prefix + n + if hasattr(c, "upgrade_state_dict_named"): + c.upgrade_state_dict_named(state_dict, name) + elif hasattr(c, "upgrade_state_dict"): + c.upgrade_state_dict(state_dict) + do_upgrade(c, name) + + do_upgrade(self, name) + + def set_num_updates(self, num_updates): + """State from trainer to pass along to model at every update.""" + for m in self.modules(): + if hasattr(m, "set_num_updates") and m != self: + m.set_num_updates(num_updates) + + def prepare_for_inference_(self, cfg: DictConfig): + """Prepare model for inference.""" + kwargs = {} + kwargs["beamable_mm_beam_size"] = ( + None + if getattr(cfg.generation, "no_beamable_mm", False) + else getattr(cfg.generation, "beam", 5) + ) + kwargs["need_attn"] = getattr(cfg.generation, "print_alignment", False) + if getattr(cfg.generation, "retain_dropout", False): + kwargs["retain_dropout"] = cfg.generation.retain_dropout + kwargs["retain_dropout_modules"] = cfg.generation.retain_dropout_modules + self.make_generation_fast_(**kwargs) + + def make_generation_fast_(self, **kwargs): + """ + Legacy entry point to optimize model for faster generation. + Prefer prepare_for_inference_. + """ + if self._is_generation_fast: + return # only apply once + self._is_generation_fast = True + + # remove weight norm from all modules in the network + def apply_remove_weight_norm(module): + try: + nn.utils.remove_weight_norm(module) + except (AttributeError, ValueError): # this module didn't have weight norm + return + + self.apply(apply_remove_weight_norm) + + def apply_make_generation_fast_(module, prefix): + if len(prefix) > 0: + prefix += "." + + base_func = BaseFairseqModel.make_generation_fast_ + for n, m in module.named_modules(): + if ( + m != self + and hasattr(m, "make_generation_fast_") + # don't call this implementation again, e.g., if + # children modules also inherit from BaseFairseqModel + and m.make_generation_fast_.__func__ is not base_func + ): + name = prefix + n + m.make_generation_fast_(name=name, **kwargs) + + apply_make_generation_fast_(self, "") + + def train(mode=True): + if mode: + raise RuntimeError("cannot train after make_generation_fast") + + # this model should no longer be used for training + self.eval() + self.train = train + + def prepare_for_onnx_export_(self, **kwargs): + """Make model exportable via ONNX trace.""" + seen = set() + + def apply_prepare_for_onnx_export_(module): + if ( + module != self + and hasattr(module, "prepare_for_onnx_export_") + and module not in seen + ): + seen.add(module) + module.prepare_for_onnx_export_(**kwargs) + + self.apply(apply_prepare_for_onnx_export_) + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + **kwargs, + ): + """ + Load a :class:`~fairseq.models.FairseqModel` from a pre-trained model + file. Downloads and caches the pre-trained model file if needed. + + The base implementation returns a + :class:`~fairseq.hub_utils.GeneratorHubInterface`, which can be used to + generate translations or sample from language models. The underlying + :class:`~fairseq.models.FairseqModel` can be accessed via the + *generator.models* attribute. + + Other models may override this to implement custom hub interfaces. + + Args: + model_name_or_path (str): either the name of a pre-trained model to + load or a path/URL to a pre-trained model state dict + checkpoint_file (str, optional): colon-separated list of checkpoint + files in the model archive to ensemble (default: 'model.pt') + data_name_or_path (str, optional): point args.data to the archive + at the given path/URL. Can start with '.' or './' to reuse the + model archive path. + """ + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + **kwargs, + ) + logger.info(x["args"]) + return hub_utils.GeneratorHubInterface(x["args"], x["task"], x["models"]) + + @classmethod + def hub_models(cls): + return {} + + +class FairseqEncoderDecoderModel(BaseFairseqModel): + """Base class for encoder-decoder models. + + Args: + encoder (FairseqEncoder): the encoder + decoder (FairseqDecoder): the decoder + """ + + def __init__(self, encoder, decoder): + super().__init__() + + self.encoder = encoder + self.decoder = decoder + + check_type(self.encoder, FairseqEncoder) + check_type(self.decoder, FairseqDecoder) + + def forward(self, src_tokens, src_lengths, prev_output_tokens, **kwargs): + """ + Run the forward pass for an encoder-decoder model. + + First feed a batch of source tokens through the encoder. Then, feed the + encoder output and previous decoder outputs (i.e., teacher forcing) to + the decoder to produce the next outputs:: + + encoder_out = self.encoder(src_tokens, src_lengths) + return self.decoder(prev_output_tokens, encoder_out) + + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (LongTensor): source sentence lengths of shape `(batch)` + prev_output_tokens (LongTensor): previous decoder outputs of shape + `(batch, tgt_len)`, for teacher forcing + + Returns: + tuple: + - the decoder's output of shape `(batch, tgt_len, vocab)` + - a dictionary with any model-specific outputs + """ + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + decoder_out = self.decoder( + prev_output_tokens, encoder_out=encoder_out, **kwargs + ) + return decoder_out + + def forward_decoder(self, prev_output_tokens, **kwargs): + return self.decoder(prev_output_tokens, **kwargs) + + def extract_features(self, src_tokens, src_lengths, prev_output_tokens, **kwargs): + """ + Similar to *forward* but only return features. + + Returns: + tuple: + - the decoder's features of shape `(batch, tgt_len, embed_dim)` + - a dictionary with any model-specific outputs + """ + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + features = self.decoder.extract_features( + prev_output_tokens, encoder_out=encoder_out, **kwargs + ) + return features + + def output_layer(self, features, **kwargs): + """Project features to the default output size (typically vocabulary size).""" + return self.decoder.output_layer(features, **kwargs) + + def max_positions(self): + """Maximum length supported by the model.""" + return (self.encoder.max_positions(), self.decoder.max_positions()) + + def max_decoder_positions(self): + """Maximum length supported by the decoder.""" + return self.decoder.max_positions() + + +class FairseqModel(FairseqEncoderDecoderModel): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + utils.deprecation_warning( + "FairseqModel is deprecated, please use FairseqEncoderDecoderModel " + "or BaseFairseqModel instead", + stacklevel=4, + ) + + +class FairseqMultiModel(BaseFairseqModel): + """Base class for combining multiple encoder-decoder models.""" + + def __init__(self, encoders, decoders): + super().__init__() + assert encoders.keys() == decoders.keys() + self.keys = list(encoders.keys()) + for key in self.keys: + check_type(encoders[key], FairseqEncoder) + check_type(decoders[key], FairseqDecoder) + + self.models = nn.ModuleDict( + { + key: FairseqEncoderDecoderModel(encoders[key], decoders[key]) + for key in self.keys + } + ) + + @staticmethod + def build_shared_embeddings( + dicts: Dict[str, Dictionary], + langs: List[str], + embed_dim: int, + build_embedding: callable, + pretrained_embed_path: Optional[str] = None, + ): + """ + Helper function to build shared embeddings for a set of languages after + checking that all dicts corresponding to those languages are equivalent. + + Args: + dicts: Dict of lang_id to its corresponding Dictionary + langs: languages that we want to share embeddings for + embed_dim: embedding dimension + build_embedding: callable function to actually build the embedding + pretrained_embed_path: Optional path to load pretrained embeddings + """ + shared_dict = dicts[langs[0]] + if any(dicts[lang] != shared_dict for lang in langs): + raise ValueError( + "--share-*-embeddings requires a joined dictionary: " + "--share-encoder-embeddings requires a joined source " + "dictionary, --share-decoder-embeddings requires a joined " + "target dictionary, and --share-all-embeddings requires a " + "joint source + target dictionary." + ) + return build_embedding(shared_dict, embed_dim, pretrained_embed_path) + + def forward(self, src_tokens, src_lengths, prev_output_tokens, **kwargs): + raise NotImplementedError + + def max_positions(self): + """Maximum length supported by the model.""" + return { + key: ( + self.models[key].encoder.max_positions(), + self.models[key].decoder.max_positions(), + ) + for key in self.keys + } + + def max_decoder_positions(self): + """Maximum length supported by the decoder.""" + return min(model.decoder.max_positions() for model in self.models.values()) + + @property + def encoder(self): + return self.models[self.keys[0]].encoder + + @property + def decoder(self): + return self.models[self.keys[0]].decoder + + def forward_decoder(self, prev_output_tokens, **kwargs): + return self.decoder(prev_output_tokens, **kwargs) + + def load_state_dict( + self, + state_dict, + strict=True, + model_cfg=None, + args: Optional[Namespace] = None, + ): + """Copies parameters and buffers from *state_dict* into this module and + its descendants. + + Overrides the method in :class:`nn.Module`. Compared with that method + this additionally "upgrades" *state_dicts* from old checkpoints. + """ + + if model_cfg is None and args is not None: + logger.warn( + "using 'args' is deprecated, please update your code to use dataclass config" + ) + model_cfg = convert_namespace_to_omegaconf(args).model + + self.upgrade_state_dict(state_dict) + + from fairseq.checkpoint_utils import prune_state_dict + + new_state_dict = prune_state_dict(state_dict, model_cfg) + return super().load_state_dict(new_state_dict, strict) + + +class FairseqLanguageModel(BaseFairseqModel): + """Base class for decoder-only models. + + Args: + decoder (FairseqDecoder): the decoder + """ + + def __init__(self, decoder): + super().__init__() + self.decoder = decoder + check_type(self.decoder, FairseqDecoder) + + def forward(self, src_tokens, **kwargs): + """ + Run the forward pass for a decoder-only model. + + Feeds a batch of tokens through the decoder to predict the next tokens. + + Args: + src_tokens (LongTensor): tokens on which to condition the decoder, + of shape `(batch, tgt_len)` + src_lengths (LongTensor): source sentence lengths of shape `(batch)` + + Returns: + tuple: + - the decoder's output of shape `(batch, seq_len, vocab)` + - a dictionary with any model-specific outputs + """ + return self.decoder(src_tokens, **kwargs) + + def forward_decoder(self, prev_output_tokens, **kwargs): + return self.decoder(prev_output_tokens, **kwargs) + + def extract_features(self, src_tokens, **kwargs): + """ + Similar to *forward* but only return features. + + Returns: + tuple: + - the decoder's features of shape `(batch, seq_len, embed_dim)` + - a dictionary with any model-specific outputs + """ + return self.decoder.extract_features(src_tokens, **kwargs) + + def output_layer(self, features, **kwargs): + """Project features to the default output size (typically vocabulary size).""" + return self.decoder.output_layer(features, **kwargs) + + def max_positions(self): + """Maximum length supported by the model.""" + return self.decoder.max_positions() + + def max_decoder_positions(self): + """Maximum length supported by the decoder.""" + return self.decoder.max_positions() + + @property + def supported_targets(self): + return {"future"} + + +class FairseqEncoderModel(BaseFairseqModel): + """Base class for encoder-only models. + + Args: + encoder (FairseqEncoder): the encoder + """ + + def __init__(self, encoder): + super().__init__() + self.encoder = encoder + check_type(self.encoder, FairseqEncoder) + + def forward(self, src_tokens, src_lengths, **kwargs): + """ + Run the forward pass for a encoder-only model. + + Feeds a batch of tokens through the encoder to generate features. + + Args: + src_tokens (LongTensor): input tokens of shape `(batch, src_len)` + src_lengths (LongTensor): source sentence lengths of shape `(batch)` + + Returns: + the encoder's output, typically of shape `(batch, src_len, features)` + """ + return self.encoder(src_tokens, src_lengths, **kwargs) + + def get_normalized_probs(self, net_output, log_probs, sample=None): + """Get normalized probabilities (or log probs) from a net's output.""" + encoder_out = net_output["encoder_out"] + if torch.is_tensor(encoder_out): + logits = encoder_out.float() + if log_probs: + return F.log_softmax(logits, dim=-1) + else: + return F.softmax(logits, dim=-1) + raise NotImplementedError + + def max_positions(self): + """Maximum length supported by the model.""" + return self.encoder.max_positions() diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/fconv.py b/PyTorch/NLP/new-Transformer/fairseq/models/fconv.py new file mode 100644 index 00000000..c99a2151 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/fconv.py @@ -0,0 +1,756 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + FairseqIncrementalDecoder, + register_model, + register_model_architecture, +) +from fairseq.modules import ( + AdaptiveSoftmax, + BeamableMM, + FairseqDropout, + GradMultiply, + LearnedPositionalEmbedding, + LinearizedConvolution, +) + + +@register_model("fconv") +class FConvModel(FairseqEncoderDecoderModel): + """ + A fully convolutional model, i.e. a convolutional encoder and a + convolutional decoder, as described in `"Convolutional Sequence to Sequence + Learning" (Gehring et al., 2017) `_. + + Args: + encoder (FConvEncoder): the encoder + decoder (FConvDecoder): the decoder + + The Convolutional model provides the following named architectures and + command-line arguments: + + .. argparse:: + :ref: fairseq.models.fconv_parser + :prog: + """ + + @classmethod + def hub_models(cls): + def moses_subword(path): + return { + "path": path, + "tokenizer": "moses", + "bpe": "subword_nmt", + } + + return { + "conv.wmt14.en-fr": moses_subword( + "https://dl.fbaipublicfiles.com/fairseq/models/wmt14.v2.en-fr.fconv-py.tar.bz2" + ), + "conv.wmt14.en-de": moses_subword( + "https://dl.fbaipublicfiles.com/fairseq/models/wmt14.en-de.fconv-py.tar.bz2" + ), + "conv.wmt17.en-de": moses_subword( + "https://dl.fbaipublicfiles.com/fairseq/models/wmt17.v2.en-de.fconv-py.tar.bz2" + ), + } + + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + self.encoder.num_attention_layers = sum( + layer is not None for layer in decoder.attention + ) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--dropout', type=float, metavar='D', + help='dropout probability') + parser.add_argument('--encoder-embed-dim', type=int, metavar='N', + help='encoder embedding dimension') + parser.add_argument('--encoder-embed-path', type=str, metavar='STR', + help='path to pre-trained encoder embedding') + parser.add_argument('--encoder-layers', type=str, metavar='EXPR', + help='encoder layers [(dim, kernel_size), ...]') + parser.add_argument('--decoder-embed-dim', type=int, metavar='N', + help='decoder embedding dimension') + parser.add_argument('--decoder-embed-path', type=str, metavar='STR', + help='path to pre-trained decoder embedding') + parser.add_argument('--decoder-layers', type=str, metavar='EXPR', + help='decoder layers [(dim, kernel_size), ...]') + parser.add_argument('--decoder-out-embed-dim', type=int, metavar='N', + help='decoder output embedding dimension') + parser.add_argument('--decoder-attention', type=str, metavar='EXPR', + help='decoder attention [True, ...]') + parser.add_argument('--share-input-output-embed', action='store_true', + help='share input and output embeddings (requires' + ' --decoder-out-embed-dim and --decoder-embed-dim' + ' to be equal)') + # fmt: on + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + # make sure that all args are properly defaulted (in case there are any new ones) + base_architecture(args) + + encoder_embed_dict = None + if args.encoder_embed_path: + encoder_embed_dict = utils.parse_embedding(args.encoder_embed_path) + utils.print_embed_overlap(encoder_embed_dict, task.source_dictionary) + + decoder_embed_dict = None + if args.decoder_embed_path: + decoder_embed_dict = utils.parse_embedding(args.decoder_embed_path) + utils.print_embed_overlap(decoder_embed_dict, task.target_dictionary) + + encoder = FConvEncoder( + dictionary=task.source_dictionary, + embed_dim=args.encoder_embed_dim, + embed_dict=encoder_embed_dict, + convolutions=eval(args.encoder_layers), + dropout=args.dropout, + max_positions=args.max_source_positions, + ) + decoder = FConvDecoder( + dictionary=task.target_dictionary, + embed_dim=args.decoder_embed_dim, + embed_dict=decoder_embed_dict, + convolutions=eval(args.decoder_layers), + out_embed_dim=args.decoder_out_embed_dim, + attention=eval(args.decoder_attention), + dropout=args.dropout, + max_positions=args.max_target_positions, + share_embed=args.share_input_output_embed, + ) + return FConvModel(encoder, decoder) + + +class FConvEncoder(FairseqEncoder): + """ + Convolutional encoder consisting of `len(convolutions)` layers. + + Args: + dictionary (~fairseq.data.Dictionary): encoding dictionary + embed_dim (int, optional): embedding dimension + embed_dict (str, optional): filename from which to load pre-trained + embeddings + max_positions (int, optional): maximum supported input sequence length + convolutions (list, optional): the convolutional layer structure. Each + list item `i` corresponds to convolutional layer `i`. Layers are + given as ``(out_channels, kernel_width, [residual])``. Residual + connections are added between layers when ``residual=1`` (which is + the default behavior). + dropout (float, optional): dropout to be applied before each conv layer + """ + + def __init__( + self, + dictionary, + embed_dim=512, + embed_dict=None, + max_positions=1024, + convolutions=((512, 3),) * 20, + dropout=0.1, + ): + super().__init__(dictionary) + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + self.num_attention_layers = None + + num_embeddings = len(dictionary) + self.padding_idx = dictionary.pad() + self.embed_tokens = Embedding(num_embeddings, embed_dim, self.padding_idx) + if embed_dict: + self.embed_tokens = utils.load_embedding( + embed_dict, self.dictionary, self.embed_tokens + ) + + self.embed_positions = PositionalEmbedding( + max_positions, + embed_dim, + self.padding_idx, + ) + + convolutions = extend_conv_spec(convolutions) + in_channels = convolutions[0][0] + self.fc1 = Linear(embed_dim, in_channels, dropout=dropout) + self.projections = nn.ModuleList() + self.convolutions = nn.ModuleList() + self.residuals = [] + + layer_in_channels = [in_channels] + for _, (out_channels, kernel_size, residual) in enumerate(convolutions): + if residual == 0: + residual_dim = out_channels + else: + residual_dim = layer_in_channels[-residual] + self.projections.append( + Linear(residual_dim, out_channels) + if residual_dim != out_channels + else None + ) + if kernel_size % 2 == 1: + padding = kernel_size // 2 + else: + padding = 0 + self.convolutions.append( + ConvTBC( + in_channels, + out_channels * 2, + kernel_size, + dropout=dropout, + padding=padding, + ) + ) + self.residuals.append(residual) + in_channels = out_channels + layer_in_channels.append(out_channels) + self.fc2 = Linear(in_channels, embed_dim) + + def forward(self, src_tokens, src_lengths): + """ + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (LongTensor): lengths of each source sentence of shape + `(batch)` + + Returns: + dict: + - **encoder_out** (tuple): a tuple with two elements, where the + first element is the last encoder layer's output and the + second element is the same quantity summed with the input + embedding (used for attention). The shape of both tensors is + `(batch, src_len, embed_dim)`. + - **encoder_padding_mask** (ByteTensor): the positions of + padding elements of shape `(batch, src_len)` + """ + # embed tokens and positions + x = self.embed_tokens(src_tokens) + self.embed_positions(src_tokens) + x = self.dropout_module(x) + input_embedding = x + + # project to size of convolution + x = self.fc1(x) + + # used to mask padding in input + encoder_padding_mask = src_tokens.eq(self.padding_idx).t() # -> T x B + if not encoder_padding_mask.any(): + encoder_padding_mask = None + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + residuals = [x] + # temporal convolutions + for proj, conv, res_layer in zip( + self.projections, self.convolutions, self.residuals + ): + if res_layer > 0: + residual = residuals[-res_layer] + residual = residual if proj is None else proj(residual) + else: + residual = None + + if encoder_padding_mask is not None: + x = x.masked_fill(encoder_padding_mask.unsqueeze(-1), 0) + + x = self.dropout_module(x) + if conv.kernel_size[0] % 2 == 1: + # padding is implicit in the conv + x = conv(x) + else: + padding_l = (conv.kernel_size[0] - 1) // 2 + padding_r = conv.kernel_size[0] // 2 + x = F.pad(x, (0, 0, 0, 0, padding_l, padding_r)) + x = conv(x) + x = F.glu(x, dim=2) + + if residual is not None: + x = (x + residual) * math.sqrt(0.5) + residuals.append(x) + + # T x B x C -> B x T x C + x = x.transpose(1, 0) + + # project back to size of embedding + x = self.fc2(x) + + if encoder_padding_mask is not None: + encoder_padding_mask = encoder_padding_mask.t() # -> B x T + x = x.masked_fill(encoder_padding_mask.unsqueeze(-1), 0) + + # scale gradients (this only affects backward, not forward) + x = GradMultiply.apply(x, 1.0 / (2.0 * self.num_attention_layers)) + + # add output to input embedding for attention + y = (x + input_embedding) * math.sqrt(0.5) + + return { + "encoder_out": (x, y), + "encoder_padding_mask": encoder_padding_mask, # B x T + } + + def reorder_encoder_out(self, encoder_out, new_order): + if encoder_out["encoder_out"] is not None: + encoder_out["encoder_out"] = ( + encoder_out["encoder_out"][0].index_select(0, new_order), + encoder_out["encoder_out"][1].index_select(0, new_order), + ) + if encoder_out["encoder_padding_mask"] is not None: + encoder_out["encoder_padding_mask"] = encoder_out[ + "encoder_padding_mask" + ].index_select(0, new_order) + return encoder_out + + def max_positions(self): + """Maximum input length supported by the encoder.""" + return self.embed_positions.max_positions + + +class AttentionLayer(nn.Module): + def __init__(self, conv_channels, embed_dim, bmm=None): + super().__init__() + # projects from output of convolution to embedding dimension + self.in_projection = Linear(conv_channels, embed_dim) + # projects from embedding dimension to convolution size + self.out_projection = Linear(embed_dim, conv_channels) + + self.bmm = bmm if bmm is not None else torch.bmm + + def forward(self, x, target_embedding, encoder_out, encoder_padding_mask): + residual = x + + # attention + x = (self.in_projection(x) + target_embedding) * math.sqrt(0.5) + x = self.bmm(x, encoder_out[0]) + + # don't attend over padding + if encoder_padding_mask is not None: + x = ( + x.float() + .masked_fill(encoder_padding_mask.unsqueeze(1), float("-inf")) + .type_as(x) + ) # FP16 support: cast to float and back + + # softmax over last dim + sz = x.size() + x = F.softmax(x.view(sz[0] * sz[1], sz[2]), dim=1) + x = x.view(sz) + attn_scores = x + + x = self.bmm(x, encoder_out[1]) + + # scale attention output (respecting potentially different lengths) + s = encoder_out[1].size(1) + if encoder_padding_mask is None: + x = x * (s * math.sqrt(1.0 / s)) + else: + s = s - encoder_padding_mask.type_as(x).sum( + dim=1, keepdim=True + ) # exclude padding + s = s.unsqueeze(-1) + x = x * (s * s.rsqrt()) + + # project back + x = (self.out_projection(x) + residual) * math.sqrt(0.5) + return x, attn_scores + + def make_generation_fast_(self, beamable_mm_beam_size=None, **kwargs): + """Replace torch.bmm with BeamableMM.""" + if beamable_mm_beam_size is not None: + del self.bmm + self.add_module("bmm", BeamableMM(beamable_mm_beam_size)) + + +class FConvDecoder(FairseqIncrementalDecoder): + """Convolutional decoder""" + + def __init__( + self, + dictionary, + embed_dim=512, + embed_dict=None, + out_embed_dim=256, + max_positions=1024, + convolutions=((512, 3),) * 20, + attention=True, + dropout=0.1, + share_embed=False, + positional_embeddings=True, + adaptive_softmax_cutoff=None, + adaptive_softmax_dropout=0.0, + ): + super().__init__(dictionary) + self.register_buffer("version", torch.Tensor([2])) + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + self.need_attn = True + + convolutions = extend_conv_spec(convolutions) + in_channels = convolutions[0][0] + if isinstance(attention, bool): + # expand True into [True, True, ...] and do the same with False + attention = [attention] * len(convolutions) + if not isinstance(attention, list) or len(attention) != len(convolutions): + raise ValueError( + "Attention is expected to be a list of booleans of " + "length equal to the number of layers." + ) + + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + self.embed_tokens = Embedding(num_embeddings, embed_dim, padding_idx) + if embed_dict: + self.embed_tokens = utils.load_embedding( + embed_dict, self.dictionary, self.embed_tokens + ) + + self.embed_positions = ( + PositionalEmbedding( + max_positions, + embed_dim, + padding_idx, + ) + if positional_embeddings + else None + ) + + self.fc1 = Linear(embed_dim, in_channels, dropout=dropout) + self.projections = nn.ModuleList() + self.convolutions = nn.ModuleList() + self.attention = nn.ModuleList() + self.residuals = [] + + layer_in_channels = [in_channels] + for i, (out_channels, kernel_size, residual) in enumerate(convolutions): + if residual == 0: + residual_dim = out_channels + else: + residual_dim = layer_in_channels[-residual] + self.projections.append( + Linear(residual_dim, out_channels) + if residual_dim != out_channels + else None + ) + self.convolutions.append( + LinearizedConv1d( + in_channels, + out_channels * 2, + kernel_size, + padding=(kernel_size - 1), + dropout=dropout, + ) + ) + self.attention.append( + AttentionLayer(out_channels, embed_dim) if attention[i] else None + ) + self.residuals.append(residual) + in_channels = out_channels + layer_in_channels.append(out_channels) + + self.adaptive_softmax = None + self.fc2 = self.fc3 = None + + if adaptive_softmax_cutoff is not None: + assert not share_embed + self.adaptive_softmax = AdaptiveSoftmax( + num_embeddings, + in_channels, + adaptive_softmax_cutoff, + dropout=adaptive_softmax_dropout, + ) + else: + self.fc2 = Linear(in_channels, out_embed_dim) + if share_embed: + assert out_embed_dim == embed_dim, ( + "Shared embed weights implies same dimensions " + " out_embed_dim={} vs embed_dim={}".format(out_embed_dim, embed_dim) + ) + self.fc3 = nn.Linear(out_embed_dim, num_embeddings) + self.fc3.weight = self.embed_tokens.weight + else: + self.fc3 = Linear(out_embed_dim, num_embeddings, dropout=dropout) + + def forward( + self, prev_output_tokens, encoder_out=None, incremental_state=None, **unused + ): + if encoder_out is not None: + encoder_padding_mask = encoder_out["encoder_padding_mask"] + encoder_out = encoder_out["encoder_out"] + + # split and transpose encoder outputs + encoder_a, encoder_b = self._split_encoder_out( + encoder_out, incremental_state + ) + + if self.embed_positions is not None: + pos_embed = self.embed_positions(prev_output_tokens, incremental_state) + else: + pos_embed = 0 + + if incremental_state is not None: + prev_output_tokens = prev_output_tokens[:, -1:] + x = self._embed_tokens(prev_output_tokens, incremental_state) + + # embed tokens and combine with positional embeddings + x += pos_embed + x = self.dropout_module(x) + target_embedding = x + + # project to size of convolution + x = self.fc1(x) + + # B x T x C -> T x B x C + x = self._transpose_if_training(x, incremental_state) + + # temporal convolutions + avg_attn_scores = None + num_attn_layers = len(self.attention) + residuals = [x] + for proj, conv, attention, res_layer in zip( + self.projections, self.convolutions, self.attention, self.residuals + ): + if res_layer > 0: + residual = residuals[-res_layer] + residual = residual if proj is None else proj(residual) + else: + residual = None + + x = self.dropout_module(x) + x = conv(x, incremental_state) + x = F.glu(x, dim=2) + + # attention + if attention is not None: + x = self._transpose_if_training(x, incremental_state) + + x, attn_scores = attention( + x, target_embedding, (encoder_a, encoder_b), encoder_padding_mask + ) + + if not self.training and self.need_attn: + attn_scores = attn_scores / num_attn_layers + if avg_attn_scores is None: + avg_attn_scores = attn_scores + else: + avg_attn_scores.add_(attn_scores) + + x = self._transpose_if_training(x, incremental_state) + + # residual + if residual is not None: + x = (x + residual) * math.sqrt(0.5) + residuals.append(x) + + # T x B x C -> B x T x C + x = self._transpose_if_training(x, incremental_state) + + # project back to size of vocabulary if not using adaptive softmax + if self.fc2 is not None and self.fc3 is not None: + x = self.fc2(x) + x = self.dropout_module(x) + x = self.fc3(x) + + return x, avg_attn_scores + + def reorder_incremental_state(self, incremental_state, new_order): + super().reorder_incremental_state(incremental_state, new_order) + encoder_out = utils.get_incremental_state( + self, incremental_state, "encoder_out" + ) + if encoder_out is not None: + encoder_out = tuple(eo.index_select(0, new_order) for eo in encoder_out) + utils.set_incremental_state( + self, incremental_state, "encoder_out", encoder_out + ) + + def max_positions(self): + """Maximum output length supported by the decoder.""" + return ( + self.embed_positions.max_positions + if self.embed_positions is not None + else float("inf") + ) + + def upgrade_state_dict(self, state_dict): + if utils.item(state_dict.get("decoder.version", torch.Tensor([1]))[0]) < 2: + # old models use incorrect weight norm dimension + for i, conv in enumerate(self.convolutions): + # reconfigure weight norm + nn.utils.remove_weight_norm(conv) + self.convolutions[i] = nn.utils.weight_norm(conv, dim=0) + state_dict["decoder.version"] = torch.Tensor([1]) + return state_dict + + def make_generation_fast_(self, need_attn=False, **kwargs): + self.need_attn = need_attn + + def _embed_tokens(self, tokens, incremental_state): + if incremental_state is not None: + # keep only the last token for incremental forward pass + tokens = tokens[:, -1:] + return self.embed_tokens(tokens) + + def _split_encoder_out(self, encoder_out, incremental_state): + """Split and transpose encoder outputs. + + This is cached when doing incremental inference. + """ + cached_result = utils.get_incremental_state( + self, incremental_state, "encoder_out" + ) + if cached_result is not None: + return cached_result + + # transpose only once to speed up attention layers + encoder_a, encoder_b = encoder_out + encoder_a = encoder_a.transpose(1, 2).contiguous() + result = (encoder_a, encoder_b) + + if incremental_state is not None: + utils.set_incremental_state(self, incremental_state, "encoder_out", result) + return result + + def _transpose_if_training(self, x, incremental_state): + if incremental_state is None: + x = x.transpose(0, 1) + return x + + +def extend_conv_spec(convolutions): + """ + Extends convolutional spec that is a list of tuples of 2 or 3 parameters + (kernel size, dim size and optionally how many layers behind to look for residual) + to default the residual propagation param if it is not specified + """ + extended = [] + for spec in convolutions: + if len(spec) == 3: + extended.append(spec) + elif len(spec) == 2: + extended.append(spec + (1,)) + else: + raise Exception( + "invalid number of parameters in convolution spec " + + str(spec) + + ". expected 2 or 3" + ) + return tuple(extended) + + +def Embedding(num_embeddings, embedding_dim, padding_idx): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + nn.init.normal_(m.weight, 0, 0.1) + nn.init.constant_(m.weight[padding_idx], 0) + return m + + +def PositionalEmbedding(num_embeddings, embedding_dim, padding_idx): + m = LearnedPositionalEmbedding(num_embeddings, embedding_dim, padding_idx) + nn.init.normal_(m.weight, 0, 0.1) + nn.init.constant_(m.weight[padding_idx], 0) + return m + + +def Linear(in_features, out_features, dropout=0.0): + """Weight-normalized Linear layer (input: N x T x C)""" + m = nn.Linear(in_features, out_features) + nn.init.normal_(m.weight, mean=0, std=math.sqrt((1 - dropout) / in_features)) + nn.init.constant_(m.bias, 0) + return nn.utils.weight_norm(m) + + +def LinearizedConv1d(in_channels, out_channels, kernel_size, dropout=0.0, **kwargs): + """Weight-normalized Conv1d layer optimized for decoding""" + m = LinearizedConvolution(in_channels, out_channels, kernel_size, **kwargs) + std = math.sqrt((4 * (1.0 - dropout)) / (m.kernel_size[0] * in_channels)) + nn.init.normal_(m.weight, mean=0, std=std) + nn.init.constant_(m.bias, 0) + return nn.utils.weight_norm(m, dim=2) + + +def ConvTBC(in_channels, out_channels, kernel_size, dropout=0.0, **kwargs): + """Weight-normalized Conv1d layer""" + from fairseq.modules import ConvTBC + + m = ConvTBC(in_channels, out_channels, kernel_size, **kwargs) + std = math.sqrt((4 * (1.0 - dropout)) / (m.kernel_size[0] * in_channels)) + nn.init.normal_(m.weight, mean=0, std=std) + nn.init.constant_(m.bias, 0) + return nn.utils.weight_norm(m, dim=2) + + +@register_model_architecture("fconv", "fconv") +def base_architecture(args): + args.dropout = getattr(args, "dropout", 0.1) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_layers = getattr(args, "encoder_layers", "[(512, 3)] * 20") + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_layers = getattr(args, "decoder_layers", "[(512, 3)] * 20") + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 256) + args.decoder_attention = getattr(args, "decoder_attention", "True") + args.share_input_output_embed = getattr(args, "share_input_output_embed", False) + + +@register_model_architecture("fconv", "fconv_iwslt_de_en") +def fconv_iwslt_de_en(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_layers = getattr(args, "encoder_layers", "[(256, 3)] * 4") + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 256) + args.decoder_layers = getattr(args, "decoder_layers", "[(256, 3)] * 3") + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 256) + base_architecture(args) + + +@register_model_architecture("fconv", "fconv_wmt_en_ro") +def fconv_wmt_en_ro(args): + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 512) + base_architecture(args) + + +@register_model_architecture("fconv", "fconv_wmt_en_de") +def fconv_wmt_en_de(args): + convs = "[(512, 3)] * 9" # first 9 layers have 512 units + convs += " + [(1024, 3)] * 4" # next 4 layers have 1024 units + convs += " + [(2048, 1)] * 2" # final 2 layers use 1x1 convolutions + + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 768) + args.encoder_layers = getattr(args, "encoder_layers", convs) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 768) + args.decoder_layers = getattr(args, "decoder_layers", convs) + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 512) + base_architecture(args) + + +@register_model_architecture("fconv", "fconv_wmt_en_fr") +def fconv_wmt_en_fr(args): + convs = "[(512, 3)] * 6" # first 6 layers have 512 units + convs += " + [(768, 3)] * 4" # next 4 layers have 768 units + convs += " + [(1024, 3)] * 3" # next 3 layers have 1024 units + convs += " + [(2048, 1)] * 1" # next 1 layer uses 1x1 convolutions + convs += " + [(4096, 1)] * 1" # final 1 layer uses 1x1 convolutions + + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 768) + args.encoder_layers = getattr(args, "encoder_layers", convs) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 768) + args.decoder_layers = getattr(args, "decoder_layers", convs) + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 512) + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/fconv_lm.py b/PyTorch/NLP/new-Transformer/fairseq/models/fconv_lm.py new file mode 100644 index 00000000..4b243d66 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/fconv_lm.py @@ -0,0 +1,136 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq import utils +from fairseq.models import ( + FairseqLanguageModel, + register_model, + register_model_architecture, +) +from fairseq.models.fconv import FConvDecoder +from fairseq.utils import safe_hasattr + + +@register_model("fconv_lm") +class FConvLanguageModel(FairseqLanguageModel): + def __init__(self, decoder): + super().__init__(decoder) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + parser.add_argument( + "--dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--decoder-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension", + ) + parser.add_argument( + "--decoder-layers", + type=str, + metavar="EXPR", + help="decoder layers [(dim, kernel_size), ...]", + ) + parser.add_argument( + "--decoder-out-embed-dim", + type=int, + metavar="N", + help="decoder output embedding dimension", + ) + parser.add_argument( + "--adaptive-softmax-cutoff", + metavar="EXPR", + help="comma separated list of adaptive softmax cutoff points. " + "Must be used with adaptive_loss criterion", + ) + parser.add_argument( + "--adaptive-softmax-dropout", + type=float, + metavar="D", + help="sets adaptive softmax dropout for the tail projections", + ) + parser.add_argument( + "--decoder-attention", + type=str, + metavar="EXPR", + help="decoder attention [True, ...]", + ) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + # make sure all arguments are present in older models + base_lm_architecture(args) + + if safe_hasattr(args, "max_target_positions") and not safe_hasattr( + args, "tokens_per_sample" + ): + args.tokens_per_sample = args.max_target_positions + + decoder = FConvDecoder( + dictionary=task.target_dictionary, + embed_dim=args.decoder_embed_dim, + convolutions=eval(args.decoder_layers), + out_embed_dim=args.decoder_embed_dim, + attention=eval(args.decoder_attention), + dropout=args.dropout, + max_positions=args.tokens_per_sample, + share_embed=False, + positional_embeddings=False, + adaptive_softmax_cutoff=( + utils.eval_str_list(args.adaptive_softmax_cutoff, type=int) + if args.criterion == "adaptive_loss" + else None + ), + adaptive_softmax_dropout=args.adaptive_softmax_dropout, + ) + return FConvLanguageModel(decoder) + + +@register_model_architecture("fconv_lm", "fconv_lm") +def base_lm_architecture(args): + args.dropout = getattr(args, "dropout", 0.1) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 128) + args.decoder_layers = getattr(args, "decoder_layers", "[(1268, 4)] * 13") + args.decoder_attention = getattr(args, "decoder_attention", "False") + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + + +@register_model_architecture("fconv_lm", "fconv_lm_dauphin_wikitext103") +def fconv_lm_dauphin_wikitext103(args): + layers = "[(850, 6)] * 3" + layers += " + [(850, 1)] * 1" + layers += " + [(850, 5)] * 4" + layers += " + [(850, 1)] * 1" + layers += " + [(850, 4)] * 3" + layers += " + [(1024, 4)] * 1" + layers += " + [(2048, 4)] * 1" + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 280) + args.decoder_layers = getattr(args, "decoder_layers", layers) + args.decoder_attention = getattr(args, "decoder_attention", "False") + args.adaptive_softmax_cutoff = getattr( + args, "adaptive_softmax_cutoff", "10000,20000,200000" + ) + base_lm_architecture(args) + + +@register_model_architecture("fconv_lm", "fconv_lm_dauphin_gbw") +def fconv_lm_dauphin_gbw(args): + layers = "[(512, 5)]" + layers += " + [(128, 1, 0), (128, 5, 0), (512, 1, 3)] * 3" + layers += " + [(512, 1, 0), (512, 5, 0), (1024, 1, 3)] * 3" + layers += " + [(1024, 1, 0), (1024, 5, 0), (2048, 1, 3)] * 6" + layers += " + [(1024, 1, 0), (1024, 5, 0), (4096, 1, 3)]" + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 128) + args.decoder_layers = getattr(args, "decoder_layers", layers) + args.decoder_attention = getattr(args, "decoder_attention", "False") + args.adaptive_softmax_cutoff = getattr( + args, "adaptive_softmax_cutoff", "10000,50000,200000" + ) + base_lm_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/fconv_self_att.py b/PyTorch/NLP/new-Transformer/fairseq/models/fconv_self_att.py new file mode 100644 index 00000000..8357ef78 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/fconv_self_att.py @@ -0,0 +1,674 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import math +import os + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import checkpoint_utils +from fairseq.incremental_decoding_utils import with_incremental_state +from fairseq.models import ( + CompositeEncoder, + FairseqDecoder, + FairseqEncoder, + FairseqEncoderDecoderModel, + register_model, + register_model_architecture, +) +from fairseq.modules import ( + DownsampledMultiHeadAttention, + FairseqDropout, + GradMultiply, + LayerNorm, + LearnedPositionalEmbedding, + LinearizedConvolution, +) + + +logger = logging.getLogger(__name__) + + +@register_model("fconv_self_att") +class FConvModelSelfAtt(FairseqEncoderDecoderModel): + @classmethod + def hub_models(cls): + return { + "conv.stories.pretrained": { + "path": "https://dl.fbaipublicfiles.com/fairseq/models/stories_checkpoint.tar.gz", + "checkpoint_file": "pretrained_checkpoint.pt", + "tokenizer": "nltk", + }, + "conv.stories": { + "path": "https://dl.fbaipublicfiles.com/fairseq/models/stories_checkpoint.tar.gz", + "checkpoint_file": "fusion_checkpoint.pt", + "tokenizer": "nltk", + "pretrained": "True", + "pretrained_checkpoint": "./pretrained_checkpoint.pt", + }, + # Test set containing dictionaries + "data.stories": "https://dl.fbaipublicfiles.com/fairseq/data/stories_test.tar.bz2", + } + + def __init__(self, encoder, decoder, pretrained_encoder=None): + super().__init__(encoder, decoder) + self.encoder.num_attention_layers = sum( + layer is not None for layer in decoder.attention + ) + self.pretrained_encoder = pretrained_encoder + if self.pretrained_encoder is None: + encoders = {"encoder": encoder} + else: + encoders = {"encoder": encoder, "pretrained": self.pretrained_encoder} + # for fusion model, CompositeEncoder contains both pretrained and training encoders + # these are forwarded and then combined in the decoder + self.encoder = CompositeEncoder(encoders) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--dropout', type=float, metavar='D', + help='dropout probability') + parser.add_argument('--encoder-embed-dim', type=int, metavar='N', + help='encoder embedding dimension') + parser.add_argument('--encoder-layers', type=str, metavar='EXPR', + help='encoder layers [(dim, kernel_size), ...]') + parser.add_argument('--decoder-embed-dim', type=int, metavar='N', + help='decoder embedding dimension') + parser.add_argument('--decoder-layers', type=str, metavar='EXPR', + help='decoder layers [(dim, kernel_size), ...]') + parser.add_argument('--decoder-out-embed-dim', type=int, metavar='N', + help='decoder output embedding dimension') + parser.add_argument('--decoder-attention', type=str, metavar='EXPR', + help='decoder attention [True, ...]') + parser.add_argument('--self-attention', type=str, metavar='EXPR', + help='decoder self-attention layers, ex: [True] + [False]*5') + parser.add_argument('--multihead-attention-nheads', type=int, + help='Number of heads to use in attention') + parser.add_argument('--multihead-self-attention-nheads', type=int, + help='Number of heads to use in self-attention') + parser.add_argument('--encoder-attention', type=str, metavar='EXPR', + help='encoder attention [True, ...]') + parser.add_argument('--encoder-attention-nheads', type=int, + help='Number of heads to use in encoder attention') + parser.add_argument('--project-input', type=str, metavar='EXPR', + help='Use projections in self-attention [True, ...]') + parser.add_argument('--gated-attention', type=str, metavar='EXPR', + help='Use GLU layers in self-attention projections [True, ...]') + parser.add_argument('--downsample', type=str, metavar='EXPR', + help='Use downsampling in self-attention [True, ...]') + parser.add_argument('--pretrained-checkpoint', metavar='DIR', + help='path to load checkpoint from pretrained model') + parser.add_argument('--pretrained', type=str, metavar='EXPR', + help='use pretrained model when training [True, ...]') + # fmt: on + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + trained_encoder, trained_decoder = None, None + pretrained = eval(args.pretrained) + if pretrained: + logger.info("loading pretrained model") + if not os.path.exists(args.pretrained_checkpoint): + new_pretrained_checkpoint = os.path.join( + args.data, args.pretrained_checkpoint + ) + if os.path.exists(new_pretrained_checkpoint): + args.pretrained_checkpoint = new_pretrained_checkpoint + trained_model = checkpoint_utils.load_model_ensemble( + filenames=[args.pretrained_checkpoint], + task=task, + )[0][0] + trained_decoder = list(trained_model.children())[1] + trained_encoder = list(trained_model.children())[0] + + # freeze pretrained model + for param in trained_decoder.parameters(): + param.requires_grad = False + for param in trained_encoder.parameters(): + param.requires_grad = False + + encoder = FConvEncoder( + task.source_dictionary, + embed_dim=args.encoder_embed_dim, + convolutions=eval(args.encoder_layers), + dropout=args.dropout, + max_positions=args.max_source_positions, + attention=eval(args.encoder_attention), + attention_nheads=args.encoder_attention_nheads, + ) + + decoder = FConvDecoder( + task.target_dictionary, + embed_dim=args.decoder_embed_dim, + convolutions=eval(args.decoder_layers), + out_embed_dim=args.decoder_out_embed_dim, + attention=eval(args.decoder_attention), + dropout=args.dropout, + max_positions=args.max_target_positions, + selfattention=eval(args.self_attention), + attention_nheads=args.multihead_attention_nheads, + selfattention_nheads=args.multihead_self_attention_nheads, + project_input=eval(args.project_input), + gated_attention=eval(args.gated_attention), + downsample=eval(args.downsample), + pretrained=pretrained, + trained_decoder=trained_decoder, + ) + model = FConvModelSelfAtt(encoder, decoder, trained_encoder) + + return model + + @property + def pretrained(self): + return self.pretrained_encoder is not None + + +class FConvEncoder(FairseqEncoder): + """Convolutional encoder""" + + def __init__( + self, + dictionary, + embed_dim=512, + max_positions=1024, + convolutions=((512, 3),) * 20, + dropout=0.1, + attention=False, + attention_nheads=1, + ): + super().__init__(dictionary) + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + self.num_attention_layers = None + + num_embeddings = len(dictionary) + self.padding_idx = dictionary.pad() + self.embed_tokens = Embedding(num_embeddings, embed_dim, self.padding_idx) + self.embed_positions = PositionalEmbedding( + max_positions, + embed_dim, + self.padding_idx, + ) + + def expand_bool_array(val): + if isinstance(val, bool): + # expand True into [True, True, ...] and do the same with False + return [val] * len(convolutions) + return val + + attention = expand_bool_array(attention) + + in_channels = convolutions[0][0] + self.fc1 = Linear(embed_dim, in_channels, dropout=dropout) + self.projections = nn.ModuleList() + self.convolutions = nn.ModuleList() + self.attention = nn.ModuleList() + self.attproj = nn.ModuleList() + for i, (out_channels, kernel_size) in enumerate(convolutions): + self.projections.append( + Linear(in_channels, out_channels) + if in_channels != out_channels + else None + ) + self.convolutions.append( + ConvTBC(in_channels, out_channels * 2, kernel_size, dropout=dropout) + ) + + self.attention.append( + SelfAttention(out_channels, embed_dim, attention_nheads) + if attention[i] + else None + ) + in_channels = out_channels + + self.fc2 = Linear(in_channels, embed_dim) + + def forward(self, src_tokens, src_lengths): + # embed tokens and positions + x = self.embed_tokens(src_tokens) + self.embed_positions(src_tokens) + x = self.dropout_module(x) + input_embedding = x.transpose(0, 1) + + # project to size of convolution + x = self.fc1(x) + + encoder_padding_mask = src_tokens.eq(self.padding_idx).t() # -> T x B + if not encoder_padding_mask.any(): + encoder_padding_mask = None + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + # temporal convolutions + for proj, conv, attention in zip( + self.projections, self.convolutions, self.attention + ): + residual = x if proj is None else proj(x) + + if encoder_padding_mask is not None: + x = x.masked_fill(encoder_padding_mask.unsqueeze(-1), 0) + + x = self.dropout_module(x) + padding_l = (conv.kernel_size[0] - 1) // 2 + padding_r = conv.kernel_size[0] // 2 + x = F.pad(x, (0, 0, 0, 0, padding_l, padding_r)) + x = conv(x) + x = F.glu(x, dim=2) + if attention is not None: + x = attention(x) + x = (x + residual) * math.sqrt(0.5) + + # T x B x C -> B x T x C + x = x.transpose(1, 0) + + # project back to size of embedding + x = self.fc2(x) + + if encoder_padding_mask is not None: + encoder_padding_mask = encoder_padding_mask.t() # -> B x T + x = x.masked_fill(encoder_padding_mask.unsqueeze(-1), 0) + + # scale gradients (this only affects backward, not forward) + x = GradMultiply.apply(x, 1.0 / (2.0 * self.num_attention_layers)) + + # add output to input embedding for attention + y = (x + input_embedding.transpose(0, 1)) * math.sqrt(0.5) + + return { + "encoder_out": (x, y), + "encoder_padding_mask": encoder_padding_mask, # B x T + } + + def reorder_encoder_out(self, encoder_out, new_order): + encoder_out["encoder_out"] = tuple( + eo.index_select(0, new_order) for eo in encoder_out["encoder_out"] + ) + + if encoder_out["encoder_padding_mask"] is not None: + encoder_out["encoder_padding_mask"] = encoder_out[ + "encoder_padding_mask" + ].index_select(0, new_order) + + if "pretrained" in encoder_out: + encoder_out["pretrained"]["encoder_out"] = tuple( + eo.index_select(0, new_order) + for eo in encoder_out["pretrained"]["encoder_out"] + ) + + return encoder_out + + def max_positions(self): + """Maximum input length supported by the encoder.""" + return self.embed_positions.max_positions + + +@with_incremental_state +class FConvDecoder(FairseqDecoder): + """Convolutional decoder""" + + def __init__( + self, + dictionary, + embed_dim=512, + out_embed_dim=256, + max_positions=1024, + convolutions=((512, 3),) * 8, + attention=True, + dropout=0.1, + selfattention=False, + attention_nheads=1, + selfattention_nheads=1, + project_input=False, + gated_attention=False, + downsample=False, + pretrained=False, + trained_decoder=None, + ): + super().__init__(dictionary) + self.register_buffer("version", torch.Tensor([2])) + self.pretrained = pretrained + self.pretrained_decoder = trained_decoder + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + self.need_attn = True + in_channels = convolutions[0][0] + + def expand_bool_array(val): + if isinstance(val, bool): + # expand True into [True, True, ...] and do the same with False + return [val] * len(convolutions) + return val + + attention = expand_bool_array(attention) + selfattention = expand_bool_array(selfattention) + + if not isinstance(attention, list) or len(attention) != len(convolutions): + raise ValueError( + "Attention is expected to be a list of booleans of " + "length equal to the number of layers." + ) + + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + self.embed_tokens = Embedding(num_embeddings, embed_dim, padding_idx) + + self.embed_positions = PositionalEmbedding( + max_positions, + embed_dim, + padding_idx, + ) + + self.fc1 = Linear(embed_dim, in_channels, dropout=dropout) + self.projections = nn.ModuleList() + self.convolutions = nn.ModuleList() + self.attention = nn.ModuleList() + self.selfattention = nn.ModuleList() + self.attproj = nn.ModuleList() + for i, (out_channels, kernel_size) in enumerate(convolutions): + self.projections.append( + Linear(in_channels, out_channels) + if in_channels != out_channels + else None + ) + self.convolutions.append( + LinearizedConv1d( + in_channels, + out_channels * 2, + kernel_size, + padding=(kernel_size - 1), + dropout=dropout, + ) + ) + + self.attention.append( + DownsampledMultiHeadAttention( + out_channels, + embed_dim, + attention_nheads, + project_input=project_input, + gated=False, + downsample=False, + ) + if attention[i] + else None + ) + + self.attproj.append( + Linear(out_channels, embed_dim, dropout=dropout) + if attention[i] + else None + ) + self.selfattention.append( + SelfAttention( + out_channels, + embed_dim, + selfattention_nheads, + project_input=project_input, + gated=gated_attention, + downsample=downsample, + ) + if selfattention[i] + else None + ) + in_channels = out_channels + + self.fc2 = Linear(in_channels, out_embed_dim) + self.fc3 = Linear(out_embed_dim, num_embeddings, dropout=dropout) + + # model fusion + if self.pretrained: + # independent gates are learned from the concatenated input + self.gate1 = nn.Sequential( + Linear(out_embed_dim * 2, out_embed_dim), nn.Sigmoid() + ) + self.gate2 = nn.Sequential( + Linear(out_embed_dim * 2, out_embed_dim), nn.Sigmoid() + ) + # pretrained and trained models are joined + self.joining = nn.Sequential( + Linear(out_embed_dim * 2, out_embed_dim * 2), + LayerNorm(out_embed_dim * 2), + nn.GLU(), + Linear(out_embed_dim, out_embed_dim * 2), + LayerNorm(out_embed_dim * 2), + nn.GLU(), + Linear(out_embed_dim, out_embed_dim), + LayerNorm(out_embed_dim), + ) + # pretrained model contains an output layer that is nhid -> vocab size + # but the models are combined in their hidden state + # the hook stores the output of the pretrained model forward + self.pretrained_outputs = {} + + def save_output(): + def hook(a, b, output): + self.pretrained_outputs["out"] = output + + return hook + + self.pretrained_decoder.fc2.register_forward_hook(save_output()) + + def forward(self, prev_output_tokens, encoder_out): + trained_encoder_out = encoder_out["pretrained"] if self.pretrained else None + encoder_out = encoder_out["encoder"]["encoder_out"] + + encoder_a, encoder_b = self._split_encoder_out(encoder_out) + + # embed positions + positions = self.embed_positions(prev_output_tokens) + + # embed tokens and positions + x = self.embed_tokens(prev_output_tokens) + positions + x = self.dropout_module(x) + target_embedding = x.transpose(0, 1) + + # project to size of convolution + x = self.fc1(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + # temporal convolutions + avg_attn_scores = None + for proj, conv, attention, selfattention, attproj in zip( + self.projections, + self.convolutions, + self.attention, + self.selfattention, + self.attproj, + ): + residual = x if proj is None else proj(x) + + x = self.dropout_module(x) + x = conv(x) + x = F.glu(x, dim=2) + + # attention + if attention is not None: + r = x + x, attn_scores = attention( + attproj(x) + target_embedding, encoder_a, encoder_b + ) + x = x + r + if not self.training and self.need_attn: + if avg_attn_scores is None: + avg_attn_scores = attn_scores + else: + avg_attn_scores.add_(attn_scores) + + if selfattention is not None: + x = selfattention(x) + + x = (x + residual) * math.sqrt(0.5) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + # project back to size of vocabulary + x = self.fc2(x) + x = self.dropout_module(x) + if not self.pretrained: + x = self.fc3(x) + + # fusion gating + if self.pretrained: + trained_x, _ = self.pretrained_decoder.forward( + prev_output_tokens, trained_encoder_out + ) + y = torch.cat([x, self.pretrained_outputs["out"]], dim=-1) + gate1 = self.gate1(y) + gate2 = self.gate2(y) + gated_x1 = gate1 * x + gated_x2 = gate2 * self.pretrained_outputs["out"] + fusion = torch.cat([gated_x1, gated_x2], dim=-1) + fusion = self.joining(fusion) + fusion_output = self.fc3(fusion) + return fusion_output, avg_attn_scores + else: + return x, avg_attn_scores + + def max_positions(self): + """Maximum output length supported by the decoder.""" + return self.embed_positions.max_positions + + def make_generation_fast_(self, need_attn=False, **kwargs): + self.need_attn = need_attn + + def _split_encoder_out(self, encoder_out): + """Split and transpose encoder outputs.""" + # transpose only once to speed up attention layers + encoder_a, encoder_b = encoder_out + encoder_a = encoder_a.transpose(0, 1).contiguous() + encoder_b = encoder_b.transpose(0, 1).contiguous() + result = (encoder_a, encoder_b) + return result + + +class SelfAttention(nn.Module): + def __init__( + self, + out_channels, + embed_dim, + num_heads, + project_input=False, + gated=False, + downsample=False, + ): + super().__init__() + self.attention = DownsampledMultiHeadAttention( + out_channels, + embed_dim, + num_heads, + dropout=0, + bias=True, + project_input=project_input, + gated=gated, + downsample=downsample, + ) + self.in_proj_q = Linear(out_channels, embed_dim) + self.in_proj_k = Linear(out_channels, embed_dim) + self.in_proj_v = Linear(out_channels, embed_dim) + self.ln = LayerNorm(out_channels) + + def forward(self, x): + residual = x + query = self.in_proj_q(x) + key = self.in_proj_k(x) + value = self.in_proj_v(x) + x, _ = self.attention( + query, key, value, mask_future_timesteps=True, use_scalar_bias=True + ) + return self.ln(x + residual) + + +def Embedding(num_embeddings, embedding_dim, padding_idx): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + m.weight.data.normal_(0, 0.1) + return m + + +def PositionalEmbedding(num_embeddings, embedding_dim, padding_idx): + m = LearnedPositionalEmbedding(num_embeddings, embedding_dim, padding_idx) + m.weight.data.normal_(0, 0.1) + return m + + +def Linear(in_features, out_features, dropout=0.0): + """Weight-normalized Linear layer (input: N x T x C)""" + m = nn.Linear(in_features, out_features) + m.weight.data.normal_(mean=0, std=math.sqrt((1 - dropout) / in_features)) + m.bias.data.zero_() + return m + + +def LinearizedConv1d(in_channels, out_channels, kernel_size, dropout=0.0, **kwargs): + """Weight-normalized Conv1d layer optimized for decoding""" + m = LinearizedConvolution(in_channels, out_channels, kernel_size, **kwargs) + std = math.sqrt((4 * (1.0 - dropout)) / (m.kernel_size[0] * in_channels)) + m.weight.data.normal_(mean=0, std=std) + m.bias.data.zero_() + return m + + +def ConvTBC(in_channels, out_channels, kernel_size, dropout=0.0, **kwargs): + """Weight-normalized Conv1d layer""" + from fairseq.modules import ConvTBC + + m = ConvTBC(in_channels, out_channels, kernel_size, **kwargs) + std = math.sqrt((4 * (1.0 - dropout)) / (m.kernel_size[0] * in_channels)) + m.weight.data.normal_(mean=0, std=std) + m.bias.data.zero_() + return m + + +@register_model_architecture("fconv_self_att", "fconv_self_att") +def base_architecture(args): + args.dropout = getattr(args, "dropout", 0.1) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_layers = getattr(args, "encoder_layers", "[(512, 3)] * 3") + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_layers = getattr(args, "decoder_layers", "[(512, 3)] * 8") + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 256) + args.decoder_attention = getattr(args, "decoder_attention", "True") + args.self_attention = getattr(args, "self_attention", "False") + args.encoder_attention = getattr(args, "encoder_attention", "False") + args.multihead_attention_nheads = getattr(args, "multihead_attention_nheads", 1) + args.multihead_self_attention_nheads = getattr( + args, "multihead_self_attention_nheads", 1 + ) + args.encoder_attention_nheads = getattr(args, "encoder_attention_nheads", 1) + args.project_input = getattr(args, "project_input", "False") + args.gated_attention = getattr(args, "gated_attention", "False") + args.downsample = getattr(args, "downsample", "False") + args.pretrained_checkpoint = getattr(args, "pretrained_checkpoint", "") + args.pretrained = getattr(args, "pretrained", "False") + + +@register_model_architecture("fconv_self_att", "fconv_self_att_wp") +def fconv_self_att_wp(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_layers = getattr( + args, "encoder_layers", "[(128, 3)] * 2 + [(512,3)] * 1" + ) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 256) + args.decoder_layers = getattr( + args, "decoder_layers", "[(512, 4)] * 4 + [(768, 4)] * 2 + [(1024, 4)] * 1" + ) + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 256) + args.self_attention = getattr(args, "self_attention", "True") + args.multihead_self_attention_nheads = getattr( + args, "multihead_self_attention_nheads", 4 + ) + args.project_input = getattr(args, "project_input", "True") + args.gated_attention = getattr(args, "gated_attention", "True") + args.downsample = getattr(args, "downsample", "True") + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/hubert/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/hubert/__init__.py new file mode 100644 index 00000000..a1b0eabb --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/hubert/__init__.py @@ -0,0 +1,7 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .hubert import * # noqa +from .hubert_asr import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/hubert/hubert.py b/PyTorch/NLP/new-Transformer/fairseq/models/hubert/hubert.py new file mode 100644 index 00000000..0c0349eb --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/hubert/hubert.py @@ -0,0 +1,570 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from dataclasses import dataclass, field +from typing import Dict, List, Optional, Tuple + +import numpy as np +import torch +import torch.nn as nn +from omegaconf import II + +from fairseq import utils +from fairseq.data.data_utils import compute_mask_indices +from fairseq.data.dictionary import Dictionary +from fairseq.dataclass import ChoiceEnum, FairseqDataclass +from fairseq.models import BaseFairseqModel, register_model +from fairseq.models.wav2vec.wav2vec2 import ( + EXTRACTOR_MODE_CHOICES, + MASKING_DISTRIBUTION_CHOICES, + LAYER_TYPE_CHOICES, + ConvFeatureExtractionModel, + TransformerEncoder, +) +from fairseq.modules import GradMultiply, LayerNorm +from fairseq.tasks.hubert_pretraining import ( + HubertPretrainingConfig, + HubertPretrainingTask, +) + +logger = logging.getLogger(__name__) + + +@dataclass +class HubertConfig(FairseqDataclass): + label_rate: float = II("task.label_rate") + + extractor_mode: EXTRACTOR_MODE_CHOICES = field( + default="default", + metadata={ + "help": "mode for feature extractor. default has a single group " + "norm with d groups in the first conv block, whereas layer_norm " + "has layer norms in every block (meant to use with normalize=True)" + }, + ) + encoder_layers: int = field( + default=12, metadata={"help": "num encoder layers in the transformer"} + ) + encoder_embed_dim: int = field( + default=768, metadata={"help": "encoder embedding dimension"} + ) + encoder_ffn_embed_dim: int = field( + default=3072, metadata={"help": "encoder embedding dimension for FFN"} + ) + encoder_attention_heads: int = field( + default=12, metadata={"help": "num encoder attention heads"} + ) + activation_fn: ChoiceEnum(utils.get_available_activation_fns()) = field( + default="gelu", metadata={"help": "activation function to use"} + ) + layer_type: LAYER_TYPE_CHOICES = field( + default="transformer", metadata={"help": "layer type in encoder"} + ) + + # dropouts + dropout: float = field( + default=0.1, + metadata={"help": "dropout probability for the transformer"}, + ) + attention_dropout: float = field( + default=0.1, + metadata={"help": "dropout probability for attention weights"}, + ) + activation_dropout: float = field( + default=0.0, + metadata={"help": "dropout probability after activation in FFN"}, + ) + encoder_layerdrop: float = field( + default=0.0, + metadata={"help": "probability of dropping a tarnsformer layer"}, + ) + dropout_input: float = field( + default=0.0, + metadata={"help": "dropout to apply to the input (after feat extr)"}, + ) + dropout_features: float = field( + default=0.0, + metadata={"help": "dropout to apply to the features (after feat extr)"}, + ) + + final_dim: int = field( + default=0, + metadata={ + "help": "project final representations and targets to this many " + "dimensions. set to encoder_embed_dim is <= 0" + }, + ) + untie_final_proj: bool = field( + default=False, + metadata={"help": "use separate projection for each target"}, + ) + layer_norm_first: bool = field( + default=False, + metadata={"help": "apply layernorm first in the transformer"}, + ) + conv_feature_layers: str = field( + default="[(512,10,5)] + [(512,3,2)] * 4 + [(512,2,2)] * 2", + metadata={ + "help": "string describing convolutional feature extraction " + "layers in form of a python list that contains " + "[(dim, kernel_size, stride), ...]" + }, + ) + conv_bias: bool = field( + default=False, metadata={"help": "include bias in conv encoder"} + ) + logit_temp: float = field( + default=0.1, metadata={"help": "temperature to divide logits by"} + ) + target_glu: bool = field( + default=False, metadata={"help": "adds projection + glu to targets"} + ) + feature_grad_mult: float = field( + default=1.0, + metadata={"help": "multiply feature extractor var grads by this"}, + ) + + # masking + mask_length: int = field(default=10, metadata={"help": "mask length"}) + mask_prob: float = field( + default=0.65, + metadata={"help": "probability of replacing a token with mask"}, + ) + mask_selection: MASKING_DISTRIBUTION_CHOICES = field( + default="static", metadata={"help": "how to choose mask length"} + ) + mask_other: float = field( + default=0, + metadata={ + "help": "secondary mask argument " + "(used for more complex distributions), " + "see help in compute_mask_indicesh" + }, + ) + no_mask_overlap: bool = field( + default=False, metadata={"help": "whether to allow masks to overlap"} + ) + mask_min_space: int = field( + default=1, + metadata={"help": "min space between spans (if no overlap is enabled)"}, + ) + + # channel masking + mask_channel_length: int = field( + default=10, + metadata={"help": "length of the mask for features (channels)"}, + ) + mask_channel_prob: float = field( + default=0.0, + metadata={"help": "probability of replacing a feature with 0"}, + ) + mask_channel_selection: MASKING_DISTRIBUTION_CHOICES = field( + default="static", + metadata={"help": "how to choose mask length for channel masking"}, + ) + mask_channel_other: float = field( + default=0, + metadata={ + "help": "secondary mask argument " + "(used for more complex distributions), " + "see help in compute_mask_indicesh" + }, + ) + no_mask_channel_overlap: bool = field( + default=False, + metadata={"help": "whether to allow channel masks to overlap"}, + ) + mask_channel_min_space: int = field( + default=1, + metadata={"help": "min space between spans (if no overlap is enabled)"}, + ) + + # positional embeddings + conv_pos: int = field( + default=128, + metadata={"help": "number of filters for convolutional positional embeddings"}, + ) + conv_pos_groups: int = field( + default=16, + metadata={"help": "number of groups for convolutional positional embedding"}, + ) + + latent_temp: Tuple[float, float, float] = field( + default=(2, 0.5, 0.999995), + metadata={"help": "legacy (to be removed)"}, + ) + + # loss computation + skip_masked: bool = field( + default=False, + metadata={"help": "skip computing losses over masked frames"}, + ) + skip_nomask: bool = field( + default=False, + metadata={"help": "skip computing losses over unmasked frames"}, + ) + + checkpoint_activations: bool = field( + default=False, + metadata={"help": "recompute activations and save memory for extra compute"}, + ) + + # FP16 optimization + required_seq_len_multiple: int = field( + default=2, + metadata={ + "help": "pad the input to encoder such that the sequence length is divisible by multiple" + }, + ) + + # Conformer + depthwise_conv_kernel_size: int = field( + default=31, + metadata={ + "help": "depthwise-conv-kernel-size for convolution in conformer layer" + }, + ) + attn_type: str = field( + default="", + metadata={"help": "if espnet use ESPNET MHA"}, + ) + pos_enc_type: str = field( + default="abs", + metadata={"help": "Positional encoding type to use in conformer"}, + ) + fp16: bool = field(default=False, metadata={"help": "If fp16 is being used"}) + + +@register_model("hubert", dataclass=HubertConfig) +class HubertModel(BaseFairseqModel): + def __init__( + self, + cfg: HubertConfig, + task_cfg: HubertPretrainingConfig, + dictionaries: List[Dictionary], + ) -> None: + super().__init__() + logger.info(f"HubertModel Config: {cfg}") + + feature_enc_layers = eval(cfg.conv_feature_layers) # noqa + self.embed = feature_enc_layers[-1][0] + + self.feature_extractor = ConvFeatureExtractionModel( + conv_layers=feature_enc_layers, + dropout=0.0, + mode=cfg.extractor_mode, + conv_bias=cfg.conv_bias, + ) + feature_ds_rate = np.prod([s for _, _, s in feature_enc_layers]) + self.feat2tar_ratio = cfg.label_rate * feature_ds_rate / task_cfg.sample_rate + + self.post_extract_proj = ( + nn.Linear(self.embed, cfg.encoder_embed_dim) + if self.embed != cfg.encoder_embed_dim + else None + ) + + self.mask_prob = cfg.mask_prob + self.mask_selection = cfg.mask_selection + self.mask_other = cfg.mask_other + self.mask_length = cfg.mask_length + self.no_mask_overlap = cfg.no_mask_overlap + self.mask_min_space = cfg.mask_min_space + + self.mask_channel_prob = cfg.mask_channel_prob + self.mask_channel_selection = cfg.mask_channel_selection + self.mask_channel_other = cfg.mask_channel_other + self.mask_channel_length = cfg.mask_channel_length + self.no_mask_channel_overlap = cfg.no_mask_channel_overlap + self.mask_channel_min_space = cfg.mask_channel_min_space + + self.dropout_input = nn.Dropout(cfg.dropout_input) + self.dropout_features = nn.Dropout(cfg.dropout_features) + + self.feature_grad_mult = cfg.feature_grad_mult + self.logit_temp = cfg.logit_temp + self.skip_masked = cfg.skip_masked + self.skip_nomask = cfg.skip_nomask + + final_dim = cfg.final_dim if cfg.final_dim > 0 else cfg.encoder_embed_dim + + self.mask_emb = nn.Parameter( + torch.FloatTensor(cfg.encoder_embed_dim).uniform_() + ) + + self.encoder = TransformerEncoder(cfg) + self.layer_norm = LayerNorm(self.embed) + + self.target_glu = None + if cfg.target_glu: + self.target_glu = nn.Sequential( + nn.Linear(final_dim, final_dim * 2), nn.GLU() + ) + + self.untie_final_proj = cfg.untie_final_proj + if self.untie_final_proj: + self.final_proj = nn.Linear( + cfg.encoder_embed_dim, final_dim * len(dictionaries) + ) + else: + self.final_proj = nn.Linear(cfg.encoder_embed_dim, final_dim) + + # modules below are not needed during fine-tuning + if any([d is None for d in dictionaries]): + logger.info("cannot find dictionary. assume will be used for fine-tuning") + else: + self.num_classes = [len(d) for d in dictionaries] + self.label_embs_concat = nn.Parameter( + torch.FloatTensor(sum(self.num_classes), final_dim) + ) + nn.init.uniform_(self.label_embs_concat) + + def upgrade_state_dict_named(self, state_dict, name): + """Upgrade a (possibly old) state dict for new versions of fairseq.""" + + super().upgrade_state_dict_named(state_dict, name) + return state_dict + + @classmethod + def build_model(cls, cfg: HubertConfig, task: HubertPretrainingTask): + """Build a new model instance.""" + + model = HubertModel(cfg, task.cfg, task.dictionaries) + return model + + def apply_mask(self, x, padding_mask, target_list): + B, T, C = x.shape + if self.mask_prob > 0: + mask_indices = compute_mask_indices( + (B, T), + padding_mask, + self.mask_prob, + self.mask_length, + self.mask_selection, + self.mask_other, + min_masks=2, + no_overlap=self.no_mask_overlap, + min_space=self.mask_min_space, + ) + mask_indices = torch.from_numpy(mask_indices).to(x.device) + x[mask_indices] = self.mask_emb + else: + mask_indices = None + + if self.mask_channel_prob > 0: + mask_channel_indices = compute_mask_indices( + (B, C), + None, + self.mask_channel_prob, + self.mask_channel_length, + self.mask_channel_selection, + self.mask_channel_other, + no_overlap=self.no_mask_channel_overlap, + min_space=self.mask_channel_min_space, + ) + mask_channel_indices = ( + torch.from_numpy(mask_channel_indices) + .to(x.device) + .unsqueeze(1) + .expand(-1, T, -1) + ) + x[mask_channel_indices] = 0 + + return x, mask_indices + + def compute_nce(self, x, pos, negs): + neg_is_pos = (pos == negs).all(-1) + pos = pos.unsqueeze(0) + targets = torch.cat([pos, negs], dim=0) + + logits = torch.cosine_similarity(x.float(), targets.float(), dim=-1).type_as(x) + logits /= self.logit_temp + if neg_is_pos.any(): + logits[1:][neg_is_pos] = float("-inf") + logits = logits.transpose(0, 1) # (num_x, num_cls+1) + return logits + + def forward_features(self, source: torch.Tensor) -> torch.Tensor: + if self.feature_grad_mult > 0: + features = self.feature_extractor(source) + if self.feature_grad_mult != 1.0: + features = GradMultiply.apply(features, self.feature_grad_mult) + else: + with torch.no_grad(): + features = self.feature_extractor(source) + return features + + def forward_targets( + self, + features: torch.Tensor, + target_list: List[torch.Tensor], + ) -> Tuple[torch.Tensor, torch.Tensor]: + # Trim features to ensure labels exist and then get aligned labels + feat_tsz = features.size(2) + targ_tsz = min([t.size(1) for t in target_list]) + if self.feat2tar_ratio * feat_tsz > targ_tsz: + feat_tsz = int(targ_tsz / self.feat2tar_ratio) + features = features[..., :feat_tsz] + target_inds = torch.arange(feat_tsz).float() * self.feat2tar_ratio + target_list = [t[:, target_inds.long()] for t in target_list] + return features, target_list + + def forward_padding_mask( + self, + features: torch.Tensor, + padding_mask: torch.Tensor, + ) -> torch.Tensor: + extra = padding_mask.size(1) % features.size(1) + if extra > 0: + padding_mask = padding_mask[:, :-extra] + padding_mask = padding_mask.view(padding_mask.size(0), features.size(1), -1) + padding_mask = padding_mask.all(-1) + return padding_mask + + def forward( + self, + source: torch.Tensor, + target_list: Optional[List[torch.Tensor]] = None, + padding_mask: Optional[torch.Tensor] = None, + mask: bool = True, + features_only: bool = False, + output_layer: Optional[int] = None, + ) -> Dict[str, torch.Tensor]: + """output layer is 1-based""" + features = self.forward_features(source) + if target_list is not None: + features, target_list = self.forward_targets(features, target_list) + + features_pen = features.float().pow(2).mean() + + features = features.transpose(1, 2) + features = self.layer_norm(features) + unmasked_features = features.clone() + + if padding_mask is not None: + padding_mask = self.forward_padding_mask(features, padding_mask) + + if self.post_extract_proj is not None: + features = self.post_extract_proj(features) + + features = self.dropout_input(features) + unmasked_features = self.dropout_features(unmasked_features) + + if mask: + x, mask_indices = self.apply_mask(features, padding_mask, target_list) + else: + x = features + mask_indices = None + + # feature: (B, T, D), float + # target: (B, T), long + # x: (B, T, D), float + # padding_mask: (B, T), bool + # mask_indices: (B, T), bool + x, _ = self.encoder( + x, + padding_mask=padding_mask, + layer=None if output_layer is None else output_layer - 1, + ) + + if features_only: + return {"x": x, "padding_mask": padding_mask, "features": features} + + def compute_pred(proj_x, target, label_embs): + # compute logits for the i-th label set + y = torch.index_select(label_embs, 0, target.long()) + negs = label_embs.unsqueeze(1).expand(-1, proj_x.size(0), -1) + if self.target_glu: + y = self.target_glu(y) + negs = self.target_glu(negs) + # proj_x: (S, D) + # y: (S, D) + # negs: (Neg, S, D) + return self.compute_nce(proj_x, y, negs) + + label_embs_list = self.label_embs_concat.split(self.num_classes, 0) + + if not self.skip_masked: + masked_indices = torch.logical_and(~padding_mask, mask_indices) + proj_x_m = self.final_proj(x[masked_indices]) + if self.untie_final_proj: + proj_x_m_list = proj_x_m.chunk(len(target_list), dim=-1) + else: + proj_x_m_list = [proj_x_m for _ in range(len(target_list))] + logit_m_list = [ + compute_pred(proj_x_m, t[masked_indices], label_embs_list[i]) + for i, (proj_x_m, t) in enumerate(zip(proj_x_m_list, target_list)) + ] + else: + logit_m_list = [None for _ in target_list] + + if not self.skip_nomask: + nomask_indices = torch.logical_and(~padding_mask, ~mask_indices) + proj_x_u = self.final_proj(x[nomask_indices]) + if self.untie_final_proj: + proj_x_u_list = proj_x_u.chunk(len(target_list), dim=-1) + else: + proj_x_u_list = [proj_x_u for _ in range(len(target_list))] + + logit_u_list = [ + compute_pred(proj_x_u, t[nomask_indices], label_embs_list[i]) + for i, (proj_x_u, t) in enumerate(zip(proj_x_u_list, target_list)) + ] + else: + logit_u_list = [None for _ in target_list] + + result = { + "logit_m_list": logit_m_list, + "logit_u_list": logit_u_list, + "padding_mask": padding_mask, + "features_pen": features_pen, + } + return result + + def extract_features( + self, + source: torch.Tensor, + padding_mask: Optional[torch.Tensor] = None, + mask: bool = False, + ret_conv: bool = False, + output_layer: Optional[int] = None, + ) -> Tuple[torch.Tensor, torch.Tensor]: + res = self.forward( + source, + padding_mask=padding_mask, + mask=mask, + features_only=True, + output_layer=output_layer, + ) + feature = res["features"] if ret_conv else res["x"] + return feature, res["padding_mask"] + + def get_logits(self, net_output, is_masked=True): + if is_masked: + logits_list = net_output["logit_m_list"] + else: + logits_list = net_output["logit_u_list"] + logits_list = [x.float() for x in logits_list if x is not None] + return logits_list + + def get_targets(self, net_output, is_masked=True): + logits_list = self.get_logits(net_output, is_masked) + targets_list = [x.new_zeros(x.size(0), dtype=torch.long) for x in logits_list] + return targets_list + + def get_extra_losses(self, net_output): + extra_losses = [] + names = [] + + if "features_pen" in net_output: + extra_losses.append(net_output["features_pen"]) + names.append("features_pen") + + return extra_losses, names + + def remove_pretraining_modules(self): + self.target_glu = None + self.final_proj = None diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/hubert/hubert_asr.py b/PyTorch/NLP/new-Transformer/fairseq/models/hubert/hubert_asr.py new file mode 100644 index 00000000..8e06a2e6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/hubert/hubert_asr.py @@ -0,0 +1,364 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import contextlib +from argparse import Namespace +from dataclasses import dataclass, field +from typing import Any + +import torch +import torch.nn as nn +from omegaconf import II, MISSING + +from fairseq import checkpoint_utils, tasks, utils +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.utils import convert_namespace_to_omegaconf +from fairseq.models import BaseFairseqModel, FairseqEncoder, register_model +from fairseq.models.hubert.hubert import MASKING_DISTRIBUTION_CHOICES +from fairseq.tasks import FairseqTask + + +@dataclass +class HubertAsrConfig(FairseqDataclass): + w2v_path: str = field(default=MISSING, metadata={"help": "path to hubert model"}) + no_pretrained_weights: bool = field( + default=False, + metadata={"help": "if true, does not load pretrained weights"}, + ) + dropout_input: float = field( + default=0.0, + metadata={"help": "dropout to apply to the input (after feat extr)"}, + ) + final_dropout: float = field( + default=0.0, + metadata={"help": "dropout after transformer and before final projection"}, + ) + dropout: float = field( + default=0.0, + metadata={"help": "dropout probability inside hubert model"}, + ) + attention_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability for attention weights " "inside hubert model" + }, + ) + activation_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability after activation in FFN " "inside hubert model" + }, + ) + + # masking + apply_mask: bool = field( + default=False, metadata={"help": "apply masking during fine-tuning"} + ) + mask_length: int = field( + default=10, metadata={"help": "repeat the mask indices multiple times"} + ) + mask_prob: float = field( + default=0.5, + metadata={ + "help": "probability of replacing a token with mask " + "(normalized by length)" + }, + ) + mask_selection: MASKING_DISTRIBUTION_CHOICES = field( + default="static", metadata={"help": "how to choose masks"} + ) + mask_other: float = field( + default=0, + metadata={ + "help": "secondary mask argument " + "(used for more complex distributions), " + "see help in compute_mask_indices" + }, + ) + no_mask_overlap: bool = field( + default=False, metadata={"help": "whether to allow masks to overlap"} + ) + + # channel masking + mask_channel_length: int = field( + default=10, + metadata={"help": "length of the mask for features (channels)"}, + ) + mask_channel_prob: float = field( + default=0.0, + metadata={"help": "probability of replacing a feature with 0"}, + ) + mask_channel_selection: MASKING_DISTRIBUTION_CHOICES = field( + default="static", + metadata={"help": "how to choose mask length for channel masking"}, + ) + mask_channel_other: float = field( + default=0, + metadata={ + "help": "secondary mask argument " + "(used for more complex distributions), " + "see help in compute_mask_indices" + }, + ) + no_mask_channel_overlap: bool = field( + default=False, + metadata={"help": "whether to allow channel masks to overlap"}, + ) + freeze_finetune_updates: int = field( + default=0, + metadata={"help": "dont finetune hubert for this many updates"}, + ) + feature_grad_mult: float = field( + default=0.0, + metadata={"help": "reset feature grad mult in hubert to this"}, + ) + layerdrop: float = field( + default=0.0, + metadata={"help": "probability of dropping a layer in hubert"}, + ) + normalize: bool = II("task.normalize") + data: str = II("task.data") + + # this holds the loaded hubert args + w2v_args: Any = None + + +@dataclass +class HubertCtcConfig(HubertAsrConfig): + pass + + +@register_model("hubert_ctc", dataclass=HubertCtcConfig) +class HubertCtc(BaseFairseqModel): + def __init__(self, cfg: HubertCtcConfig, w2v_encoder: BaseFairseqModel): + super().__init__() + self.cfg = cfg + self.w2v_encoder = w2v_encoder + + def upgrade_state_dict_named(self, state_dict, name): + super().upgrade_state_dict_named(state_dict, name) + return state_dict + + @classmethod + def build_model(cls, cfg: HubertCtcConfig, task: FairseqTask): + """Build a new model instance.""" + w2v_encoder = HubertEncoder(cfg, task) + return cls(cfg, w2v_encoder) + + def get_normalized_probs(self, net_output, log_probs): + """Get normalized probabilities (or log probs) from a net's output.""" + + logits = net_output["encoder_out"] + if log_probs: + return utils.log_softmax(logits.float(), dim=-1) + else: + return utils.softmax(logits.float(), dim=-1) + + def get_logits(self, net_output): + logits = net_output["encoder_out"] + padding = net_output["encoder_padding_mask"] + if padding is not None and padding.any(): + padding = padding.T + logits[padding][..., 0] = 0 + logits[padding][..., 1:] = float("-inf") + + return logits + + def forward(self, **kwargs): + x = self.w2v_encoder(**kwargs) + return x + + +@dataclass +class HubertSeq2SeqConfig(HubertAsrConfig): + decoder_embed_dim: int = field( + default=768, metadata={"help": "decoder embedding dimension"} + ) + decoder_ffn_embed_dim: int = field( + default=3072, metadata={"help": "decoder embedding dimension for FFN"} + ) + decoder_layers: int = field(default=6, metadata={"help": "num of decoder layers"}) + decoder_layerdrop: float = field( + default=0.0, metadata={"help": "decoder layerdrop chance"} + ) + decoder_attention_heads: int = field( + default=4, metadata={"help": "num decoder attention heads"} + ) + decoder_learned_pos: bool = field( + default=False, + metadata={"help": "use learned positional embeddings in the decoder"}, + ) + decoder_normalize_before: bool = field( + default=False, + metadata={"help": "apply layernorm before each decoder block"}, + ) + no_token_positional_embeddings: bool = field( + default=False, + metadata={ + "help": "if set, disables positional embeddings " "(outside self attention)" + }, + ) + decoder_dropout: float = field( + default=0.0, metadata={"help": "dropout probability in the decoder"} + ) + decoder_attention_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability for attention weights " "inside the decoder" + }, + ) + decoder_activation_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability after activation in FFN " "inside the decoder" + }, + ) + max_target_positions: int = field( + default=2048, metadata={"help": "max target positions"} + ) + share_decoder_input_output_embed: bool = field( + default=False, + metadata={"help": "share decoder input and output embeddings"}, + ) + + +class HubertEncoder(FairseqEncoder): + def __init__(self, cfg: HubertAsrConfig, task): + self.apply_mask = cfg.apply_mask + + arg_overrides = { + "dropout": cfg.dropout, + "activation_dropout": cfg.activation_dropout, + "dropout_input": cfg.dropout_input, + "attention_dropout": cfg.attention_dropout, + "mask_length": cfg.mask_length, + "mask_prob": cfg.mask_prob, + "mask_selection": cfg.mask_selection, + "mask_other": cfg.mask_other, + "no_mask_overlap": cfg.no_mask_overlap, + "mask_channel_length": cfg.mask_channel_length, + "mask_channel_prob": cfg.mask_channel_prob, + "mask_channel_selection": cfg.mask_channel_selection, + "mask_channel_other": cfg.mask_channel_other, + "no_mask_channel_overlap": cfg.no_mask_channel_overlap, + "encoder_layerdrop": cfg.layerdrop, + "feature_grad_mult": cfg.feature_grad_mult, + } + + if cfg.w2v_args is None: + state = checkpoint_utils.load_checkpoint_to_cpu(cfg.w2v_path, arg_overrides) + w2v_args = state.get("cfg", None) + if w2v_args is None: + w2v_args = convert_namespace_to_omegaconf(state["args"]) + cfg.w2v_args = w2v_args + else: + state = None + w2v_args = cfg.w2v_args + if isinstance(w2v_args, Namespace): + cfg.w2v_args = w2v_args = convert_namespace_to_omegaconf(w2v_args) + + assert cfg.normalize == w2v_args.task.normalize, ( + "Fine-tuning works best when data normalization is the same. " + "Please check that --normalize is set or unset for " + "both pre-training and here" + ) + + w2v_args.task.data = cfg.data + pretrain_task = tasks.setup_task(w2v_args.task) + if state is not None and "task_state" in state: + # This will load the stored "dictionaries" object + pretrain_task.load_state_dict(state["task_state"]) + else: + pretrain_task.load_state_dict(task.state_dict()) + + model = pretrain_task.build_model(w2v_args.model, from_checkpoint=True) + if state is not None and not cfg.no_pretrained_weights: + # set strict=False because we omit some modules + model.load_state_dict(state["model"], strict=False) + + model.remove_pretraining_modules() + + super().__init__(pretrain_task.source_dictionary) + + d = w2v_args.model.encoder_embed_dim + + self.w2v_model = model + + self.final_dropout = nn.Dropout(cfg.final_dropout) + self.freeze_finetune_updates = cfg.freeze_finetune_updates + self.num_updates = 0 + + if task.target_dictionary is not None: + self.proj = Linear(d, len(task.target_dictionary)) + elif getattr(cfg, "decoder_embed_dim", d) != d: + self.proj = Linear(d, cfg.decoder_embed_dim) + else: + self.proj = None + + def set_num_updates(self, num_updates): + """Set the number of parameters updates.""" + super().set_num_updates(num_updates) + self.num_updates = num_updates + + def forward(self, source, padding_mask, tbc=True, **kwargs): + + w2v_args = { + "source": source, + "padding_mask": padding_mask, + "mask": self.apply_mask and self.training, + } + + ft = self.freeze_finetune_updates <= self.num_updates + + with torch.no_grad() if not ft else contextlib.ExitStack(): + x, padding_mask = self.w2v_model.extract_features(**w2v_args) + + if tbc: + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + x = self.final_dropout(x) + + if self.proj: + x = self.proj(x) + + return { + "encoder_out": x, # T x B x C + "encoder_padding_mask": padding_mask, # B x T + "padding_mask": padding_mask, + } + + def reorder_encoder_out(self, encoder_out, new_order): + if encoder_out["encoder_out"] is not None: + encoder_out["encoder_out"] = encoder_out["encoder_out"].index_select( + 1, new_order + ) + if encoder_out["encoder_padding_mask"] is not None: + encoder_out["encoder_padding_mask"] = encoder_out[ + "encoder_padding_mask" + ].index_select(0, new_order) + return encoder_out + + def max_positions(self): + """Maximum input length supported by the encoder.""" + return None + + def upgrade_state_dict_named(self, state_dict, name): + return state_dict + + +def Embedding(num_embeddings, embedding_dim, padding_idx): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + nn.init.normal_(m.weight, mean=0, std=embedding_dim**-0.5) + nn.init.constant_(m.weight[padding_idx], 0) + return m + + +def Linear(in_features, out_features, bias=True): + m = nn.Linear(in_features, out_features, bias) + nn.init.xavier_uniform_(m.weight) + if bias: + nn.init.constant_(m.bias, 0.0) + return m diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/huggingface/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/huggingface/__init__.py new file mode 100644 index 00000000..f7911c2c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/huggingface/__init__.py @@ -0,0 +1,20 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import importlib +import os + + +# automatically import any Python files in the models/huggingface/ directory +models_dir = os.path.dirname(__file__) +for file in os.listdir(models_dir): + path = os.path.join(models_dir, file) + if ( + not file.startswith("_") + and not file.startswith(".") + and (file.endswith(".py") or os.path.isdir(path)) + ): + model_name = file[: file.find(".py")] if file.endswith(".py") else file + module = importlib.import_module("fairseq.models.huggingface." + model_name) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/huggingface/hf_gpt2.py b/PyTorch/NLP/new-Transformer/fairseq/models/huggingface/hf_gpt2.py new file mode 100644 index 00000000..3a8eb781 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/huggingface/hf_gpt2.py @@ -0,0 +1,168 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +import sys +from typing import Dict, List, Optional + +import torch +from fairseq.models import ( + FairseqIncrementalDecoder, + FairseqLanguageModel, + register_model, + register_model_architecture, +) + + +logger = logging.getLogger(__name__) + + +DEFAULT_MAX_TARGET_POSITIONS = 1024 + + +@register_model("hf_gpt2") +class HuggingFaceGPT2LanguageModel(FairseqLanguageModel): + def __init__(self, decoder): + super().__init__(decoder) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--embed-dim', type=int, metavar='N', + help='embedding dimension') + parser.add_argument('--num-attention-heads', type=int, metavar='N', + help='num attention heads') + parser.add_argument('--num-layers', type=int, metavar='N', + help='num layers') + parser.add_argument('--dropout', type=float, metavar='D', + help='dropout probability for all fully connected layers ' + 'in the embeddings, encoder, and pooler') + parser.add_argument('--attention-dropout', type=float, metavar='D', + help='dropout probability for attention weights') + # fmt: on + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + default_architecture(args) + return cls(HuggingFaceGPT2Decoder(args, task)) + + +class HuggingFaceGPT2Decoder(FairseqIncrementalDecoder): + def __init__(self, args, task): + try: + from transformers import GPT2Config, GPT2LMHeadModel + except ImportError: + raise ImportError( + "\n\nPlease install huggingface/transformers with:" + "\n\n pip install transformers" + ) + + super().__init__(task.target_dictionary) + + config = GPT2Config( + vocab_size=len(task.target_dictionary), + n_positions=args.max_target_positions + 1, + n_ctx=args.max_target_positions, + n_embd=args.embed_dim, + n_layer=args.num_layers, + n_head=args.num_attention_heads, + resid_pdrop=args.dropout, + embd_pdrop=args.dropout, + attn_pdrop=args.attention_dropout, + layer_norm_epsilon=1e-6, + ) + self.model = GPT2LMHeadModel(config) + + # set zero embedding for padding symbol + self.pad_idx = task.target_dictionary.pad() + self.model.transformer.wte.weight.data[self.pad_idx].zero_() + self.model.transformer.wpe.weight.data[0].zero_() + + def forward( + self, + prev_output_tokens, + src_lengths=None, + incremental_state: Optional[Dict[str, List[torch.Tensor]]] = None, + encoder_out=None, + ): + features = self.extract_features(prev_output_tokens, incremental_state) + lm_logits = self.model.lm_head(features) + return (lm_logits,) + + def extract_features( + self, + prev_output_tokens, + incremental_state: Optional[Dict[str, List[torch.Tensor]]] = None, + ): + if incremental_state: + past = self.get_incremental_state("past") + else: + past = None + + # don't attend to padding symbols + attention_mask = prev_output_tokens.ne(self.pad_idx).int() + + # set position ids to exclude padding symbols + position_ids = attention_mask * ( + torch.arange(1, 1 + prev_output_tokens.size(1)) + .to(prev_output_tokens) + .repeat(prev_output_tokens.size(0), 1) + ) + + outputs = self.model.transformer( + input_ids=prev_output_tokens, + past=past, + attention_mask=attention_mask, + position_ids=position_ids, + ) + last_hidden_states = outputs[0] + + if incremental_state: + self.set_incremental_state(incremental_state, "past", outputs[1]) + + return last_hidden_states + + def max_positions(self): + return self.model.config.n_positions - 1 + + +@register_model_architecture("hf_gpt2", "hf_gpt2") +def default_architecture(args): + if getattr(args, "max_target_positions", None) is None: + args.max_target_positions = getattr( + args, "tokens_per_sample", DEFAULT_MAX_TARGET_POSITIONS + ) + args.embed_dim = getattr(args, "embed_dim", 768) + args.num_attention_heads = getattr(args, "num_attention_heads", 12) + args.num_layers = getattr(args, "num_layers", 12) + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + + +@register_model_architecture("hf_gpt2", "hf_gpt2_medium") +def hf_gpt2_medium(args): + args.embed_dim = getattr(args, "embed_dim", 1024) + args.num_attention_heads = getattr(args, "num_attention_heads", 16) + args.num_layers = getattr(args, "num_layers", 24) + default_architecture(args) + + +@register_model_architecture("hf_gpt2", "hf_gpt2_large") +def hf_gpt2_large(args): + args.embed_dim = getattr(args, "embed_dim", 1280) + args.num_attention_heads = getattr(args, "num_attention_heads", 20) + args.num_layers = getattr(args, "num_layers", 36) + default_architecture(args) + + +@register_model_architecture("hf_gpt2", "hf_gpt2_xl") +def hf_gpt2_xl(args): + args.embed_dim = getattr(args, "embed_dim", 1600) + args.num_attention_heads = getattr(args, "num_attention_heads", 25) + args.num_layers = getattr(args, "num_layers", 48) + default_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/lightconv.py b/PyTorch/NLP/new-Transformer/fairseq/models/lightconv.py new file mode 100644 index 00000000..5f4f6d47 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/lightconv.py @@ -0,0 +1,1020 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from fairseq import utils +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + FairseqIncrementalDecoder, + register_model, + register_model_architecture, +) +from fairseq.modules import ( + AdaptiveSoftmax, + DynamicConv, + FairseqDropout, + LayerNorm, + LightweightConv, + MultiheadAttention, + PositionalEmbedding, +) +from fairseq.utils import safe_hasattr + + +@register_model("lightconv") +class LightConvModel(FairseqEncoderDecoderModel): + """ + LightConv and DynamicConv model from `"Pay Less Attention with Lightweight and Dynamic Convolutions" (Wu, et al, 2019) + `_. + To use LightConv please set ``--encoder-conv-type lightweight --decoder-conv-type lightweight`` + To use DynamicConv please set ``--encoder-conv-type dynamic --decoder-conv-type dynamic`` + + Args: + encoder (LightConvEncoder): the encoder + decoder (LightConvDecoder): the decoder + + The LightConv model provides the following named architectures and + command-line arguments: + + .. argparse:: + :ref: fairseq.models.lightconv_parser + :prog: + """ + + @classmethod + def hub_models(cls): + # fmt: off + + def moses_subword(path): + return { + 'path': path, + 'tokenizer': 'moses', + 'bpe': 'subword_nmt', + } + + return { + 'lightconv.no_glu.iwslt14.de-en': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/iwslt14.de-en.lightconv.tar.gz'), + 'dynamicconv.no_glu.iwslt14.de-en': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/iwslt14.de-en.dynamicconv.tar.gz'), + 'lightconv.no_glu.wmt16.en-de': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt16.en-de.joined-dict.lightconv.tar.gz'), + 'dynamicconv.no_glu.wmt16.en-de': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt16.en-de.joined-dict.dynamicconv.tar.gz'), + 'lightconv.glu.wmt16.en-de': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt16.en-de.joined-dict.lightconv-glu.tar.gz'), + 'dynamicconv.glu.wmt16.en-de': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt16.en-de.joined-dict.dynamicconv-glu.tar.gz'), + 'lightconv.glu.wmt17.en-de': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt16.en-de.joined-dict.lightconv-glu.tar.gz'), + 'dynamicconv.glu.wmt17.en-de': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt16.en-de.joined-dict.dynamicconv-glu.tar.gz'), + 'lightconv.glu.wmt14.en-fr': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt14.en-fr.joined-dict.lightconv-glu.tar.gz'), + 'dynamicconv.glu.wmt14.en-fr': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt14.en-fr.joined-dict.dynamicconv-glu.tar.gz'), + 'lightconv.glu.wmt17.zh-en': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt17.zh-en.lightconv-glu.tar.gz'), + 'dynamicconv.glu.wmt17.zh-en': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/dynamicconv/wmt17.zh-en.dynamicconv-glu.tar.gz'), + } + # fmt: on + + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + parser.add_argument( + "--dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--attention-dropout", + type=float, + metavar="D", + help="dropout probability for attention weights", + ) + parser.add_argument( + "--relu-dropout", + type=float, + metavar="D", + help="dropout probability after ReLU in FFN", + ) + parser.add_argument( + "--input-dropout", + type=float, + metavar="D", + help="dropout probability of the inputs", + ) + parser.add_argument( + "--encoder-embed-path", + type=str, + metavar="STR", + help="path to pre-trained encoder embedding", + ) + parser.add_argument( + "--encoder-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension", + ) + parser.add_argument( + "--encoder-conv-dim", + type=int, + metavar="N", + help="encoder embedding dimension", + ) + parser.add_argument( + "--encoder-ffn-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension for FFN", + ) + parser.add_argument( + "--encoder-layers", type=int, metavar="N", help="num encoder layers" + ) + parser.add_argument( + "--encoder-attention-heads", + type=int, + metavar="N", + help="num encoder attention heads or LightConv/DynamicConv heads", + ) + parser.add_argument( + "--encoder-normalize-before", + action="store_true", + help="apply layernorm before each encoder block", + ) + parser.add_argument( + "--encoder-learned-pos", + action="store_true", + help="use learned positional embeddings in the encoder", + ) + parser.add_argument( + "--decoder-embed-path", + type=str, + metavar="STR", + help="path to pre-trained decoder embedding", + ) + parser.add_argument( + "--decoder-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension", + ) + parser.add_argument( + "--decoder-conv-dim", + type=int, + metavar="N", + help="decoder embedding dimension", + ) + parser.add_argument( + "--decoder-ffn-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension for FFN", + ) + parser.add_argument( + "--decoder-layers", type=int, metavar="N", help="num decoder layers" + ) + parser.add_argument( + "--decoder-attention-heads", + type=int, + metavar="N", + help="num decoder attention heads or LightConv/DynamicConv heads", + ) + parser.add_argument( + "--decoder-learned-pos", + action="store_true", + help="use learned positional embeddings in the decoder", + ) + parser.add_argument( + "--decoder-normalize-before", + action="store_true", + help="apply layernorm before each decoder block", + ) + parser.add_argument( + "--share-decoder-input-output-embed", + action="store_true", + help="share decoder input and output embeddings", + ) + parser.add_argument( + "--share-all-embeddings", + action="store_true", + help="share encoder, decoder and output embeddings" + " (requires shared dictionary and embed dim)", + ) + parser.add_argument( + "--adaptive-softmax-cutoff", + metavar="EXPR", + help="comma separated list of adaptive softmax cutoff points. " + "Must be used with adaptive_loss criterion", + ), + parser.add_argument( + "--adaptive-softmax-dropout", + type=float, + metavar="D", + help="sets adaptive softmax dropout for the tail projections", + ) + + """LightConv and DynamicConv arguments""" + parser.add_argument( + "--encoder-kernel-size-list", + type=lambda x: utils.eval_str_list(x, int), + help='list of kernel size (default: "[3,7,15,31,31,31,31]")', + ) + parser.add_argument( + "--decoder-kernel-size-list", + type=lambda x: utils.eval_str_list(x, int), + help='list of kernel size (default: "[3,7,15,31,31,31]")', + ) + parser.add_argument( + "--encoder-glu", type=utils.eval_bool, help="glu after in proj" + ) + parser.add_argument( + "--decoder-glu", type=utils.eval_bool, help="glu after in proj" + ) + parser.add_argument( + "--encoder-conv-type", + default="dynamic", + type=str, + choices=["dynamic", "lightweight"], + help="type of convolution", + ) + parser.add_argument( + "--decoder-conv-type", + default="dynamic", + type=str, + choices=["dynamic", "lightweight"], + help="type of convolution", + ) + parser.add_argument("--weight-softmax", default=True, type=utils.eval_bool) + parser.add_argument( + "--weight-dropout", + type=float, + metavar="D", + help="dropout probability for conv weights", + ) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present in older models + base_architecture(args) + + if not safe_hasattr(args, "max_source_positions"): + args.max_source_positions = 1024 + if not safe_hasattr(args, "max_target_positions"): + args.max_target_positions = 1024 + + src_dict, tgt_dict = task.source_dictionary, task.target_dictionary + + def build_embedding(dictionary, embed_dim, path=None): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + emb = Embedding(num_embeddings, embed_dim, padding_idx) + # if provided, load from preloaded dictionaries + if path: + embed_dict = utils.parse_embedding(path) + utils.load_embedding(embed_dict, dictionary, emb) + return emb + + if args.share_all_embeddings: + if src_dict != tgt_dict: + raise RuntimeError( + "--share-all-embeddings requires a joined dictionary" + ) + if args.encoder_embed_dim != args.decoder_embed_dim: + raise RuntimeError( + "--share-all-embeddings requires --encoder-embed-dim to match --decoder-embed-dim" + ) + if args.decoder_embed_path and ( + args.decoder_embed_path != args.encoder_embed_path + ): + raise RuntimeError( + "--share-all-embeddings not compatible with --decoder-embed-path" + ) + encoder_embed_tokens = build_embedding( + src_dict, args.encoder_embed_dim, args.encoder_embed_path + ) + decoder_embed_tokens = encoder_embed_tokens + args.share_decoder_input_output_embed = True + else: + encoder_embed_tokens = build_embedding( + src_dict, args.encoder_embed_dim, args.encoder_embed_path + ) + decoder_embed_tokens = build_embedding( + tgt_dict, args.decoder_embed_dim, args.decoder_embed_path + ) + + encoder = LightConvEncoder(args, src_dict, encoder_embed_tokens) + decoder = LightConvDecoder(args, tgt_dict, decoder_embed_tokens) + return LightConvModel(encoder, decoder) + + +class LightConvEncoder(FairseqEncoder): + """ + LightConv encoder consisting of *args.encoder_layers* layers. Each layer + is a :class:`LightConvEncoderLayer`. + + Args: + args (argparse.Namespace): parsed command-line arguments + dictionary (~fairseq.data.Dictionary): encoding dictionary + embed_tokens (torch.nn.Embedding): input embedding + """ + + def __init__(self, args, dictionary, embed_tokens): + super().__init__(dictionary) + self.dropout_module = FairseqDropout( + args.dropout, module_name=self.__class__.__name__ + ) + + embed_dim = embed_tokens.embedding_dim + self.padding_idx = embed_tokens.padding_idx + self.max_source_positions = args.max_source_positions + + self.embed_tokens = embed_tokens + self.embed_scale = math.sqrt(embed_dim) + self.embed_positions = ( + PositionalEmbedding( + args.max_source_positions, + embed_dim, + self.padding_idx, + learned=args.encoder_learned_pos, + ) + if not args.no_token_positional_embeddings + else None + ) + + self.layers = nn.ModuleList([]) + self.layers.extend( + [ + LightConvEncoderLayer( + args, kernel_size=args.encoder_kernel_size_list[i] + ) + for i in range(args.encoder_layers) + ] + ) + self.register_buffer("version", torch.Tensor([2])) + self.normalize = args.encoder_normalize_before + if self.normalize: + self.layer_norm = LayerNorm(embed_dim) + + def forward(self, src_tokens, **unused): + """ + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + + Returns: + dict: + - **encoder_out** (Tensor): the last encoder layer's output of + shape `(src_len, batch, embed_dim)` + - **encoder_padding_mask** (ByteTensor): the positions of + padding elements of shape `(batch, src_len)` + """ + # embed tokens and positions + x = self.embed_scale * self.embed_tokens(src_tokens) + if self.embed_positions is not None: + x += self.embed_positions(src_tokens) + x = self.dropout_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + # compute padding mask + encoder_padding_mask = src_tokens.eq(self.padding_idx) + if not encoder_padding_mask.any(): + encoder_padding_mask = None + + # encoder layers + for layer in self.layers: + x = layer(x, encoder_padding_mask) + + if self.normalize: + x = self.layer_norm(x) + + return { + "encoder_out": x, # T x B x C + "encoder_padding_mask": encoder_padding_mask, # B x T + } + + def reorder_encoder_out(self, encoder_out, new_order): + """ + Reorder encoder output according to *new_order*. + + Args: + encoder_out: output from the ``forward()`` method + new_order (LongTensor): desired order + + Returns: + *encoder_out* rearranged according to *new_order* + """ + if encoder_out["encoder_out"] is not None: + encoder_out["encoder_out"] = encoder_out["encoder_out"].index_select( + 1, new_order + ) + if encoder_out["encoder_padding_mask"] is not None: + encoder_out["encoder_padding_mask"] = encoder_out[ + "encoder_padding_mask" + ].index_select(0, new_order) + return encoder_out + + def max_positions(self): + """Maximum input length supported by the encoder.""" + if self.embed_positions is None: + return self.max_source_positions + return min(self.max_source_positions, self.embed_positions.max_positions) + + +class LightConvDecoder(FairseqIncrementalDecoder): + """ + LightConv decoder consisting of *args.decoder_layers* layers. Each layer + is a :class:`LightConvDecoderLayer`. + + Args: + args (argparse.Namespace): parsed command-line arguments + dictionary (~fairseq.data.Dictionary): decoding dictionary + embed_tokens (torch.nn.Embedding): output embedding + no_encoder_attn (bool, optional): whether to attend to encoder outputs. + Default: ``False`` + """ + + def __init__( + self, args, dictionary, embed_tokens, no_encoder_attn=False, final_norm=True + ): + super().__init__(dictionary) + self.dropout_module = FairseqDropout( + args.dropout, module_name=self.__class__.__name__ + ) + self.share_input_output_embed = args.share_decoder_input_output_embed + + input_embed_dim = embed_tokens.embedding_dim + embed_dim = args.decoder_embed_dim + output_embed_dim = args.decoder_output_dim + + padding_idx = embed_tokens.padding_idx + self.max_target_positions = args.max_target_positions + + self.embed_tokens = embed_tokens + self.embed_scale = math.sqrt(embed_dim) # todo: try with input_embed_dim + + self.project_in_dim = ( + Linear(input_embed_dim, embed_dim, bias=False) + if embed_dim != input_embed_dim + else None + ) + + self.embed_positions = ( + PositionalEmbedding( + args.max_target_positions, + embed_dim, + padding_idx, + learned=args.decoder_learned_pos, + ) + if not args.no_token_positional_embeddings + else None + ) + + self.layers = nn.ModuleList([]) + self.layers.extend( + [ + LightConvDecoderLayer( + args, no_encoder_attn, kernel_size=args.decoder_kernel_size_list[i] + ) + for i in range(args.decoder_layers) + ] + ) + + self.adaptive_softmax = None + + self.project_out_dim = ( + Linear(embed_dim, output_embed_dim, bias=False) + if embed_dim != output_embed_dim and not args.tie_adaptive_weights + else None + ) + + if args.adaptive_softmax_cutoff is not None: + self.adaptive_softmax = AdaptiveSoftmax( + len(dictionary), + output_embed_dim, + utils.eval_str_list(args.adaptive_softmax_cutoff, type=int), + dropout=args.adaptive_softmax_dropout, + adaptive_inputs=embed_tokens if args.tie_adaptive_weights else None, + factor=args.adaptive_softmax_factor, + tie_proj=args.tie_adaptive_proj, + ) + elif not self.share_input_output_embed: + self.embed_out = nn.Parameter( + torch.Tensor(len(dictionary), output_embed_dim) + ) + nn.init.normal_(self.embed_out, mean=0, std=output_embed_dim**-0.5) + self.register_buffer("version", torch.Tensor([2])) + self.normalize = args.decoder_normalize_before and final_norm + if self.normalize: + self.layer_norm = LayerNorm(embed_dim) + + def forward( + self, prev_output_tokens, encoder_out=None, incremental_state=None, **kwargs + ): + """ + Args: + prev_output_tokens (LongTensor): previous decoder outputs of shape + `(batch, tgt_len)`, for teacher forcing + encoder_out (Tensor, optional): output from the encoder, used for + encoder-side attention + incremental_state (dict): dictionary used for storing state during + :ref:`Incremental decoding` + + Returns: + tuple: + - the last decoder layer's output of shape `(batch, tgt_len, + vocab)` + - the last decoder layer's attention weights of shape `(batch, + tgt_len, src_len)` + """ + # embed positions + positions = ( + self.embed_positions( + prev_output_tokens, + incremental_state=incremental_state, + ) + if self.embed_positions is not None + else None + ) + + if incremental_state is not None: + prev_output_tokens = prev_output_tokens[:, -1:] + if positions is not None: + positions = positions[:, -1:] + + # embed tokens and positions + x = self.embed_scale * self.embed_tokens(prev_output_tokens) + + if self.project_in_dim is not None: + x = self.project_in_dim(x) + + if positions is not None: + x += positions + x = self.dropout_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + attn = None + + inner_states = [x] + + # decoder layers + for layer in self.layers: + x, attn = layer( + x, + encoder_out["encoder_out"] if encoder_out is not None else None, + encoder_out["encoder_padding_mask"] + if encoder_out is not None + else None, + incremental_state, + ) + inner_states.append(x) + + if self.normalize: + x = self.layer_norm(x) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + if self.project_out_dim is not None: + x = self.project_out_dim(x) + + if self.adaptive_softmax is None: + # project back to size of vocabulary + if self.share_input_output_embed: + x = F.linear(x, self.embed_tokens.weight) + else: + x = F.linear(x, self.embed_out) + + return x, {"attn": attn, "inner_states": inner_states} + + def max_positions(self): + """Maximum output length supported by the decoder.""" + if self.embed_positions is None: + return self.max_target_positions + return min(self.max_target_positions, self.embed_positions.max_positions) + + def buffered_future_mask(self, tensor): + dim = tensor.size(0) + if ( + not hasattr(self, "_future_mask") + or self._future_mask is None + or self._future_mask.device != tensor.device + ): + self._future_mask = torch.triu( + utils.fill_with_neg_inf(tensor.new(dim, dim)), 1 + ) + if self._future_mask.size(0) < dim: + self._future_mask = torch.triu( + utils.fill_with_neg_inf(self._future_mask.resize_(dim, dim)), 1 + ) + return self._future_mask[:dim, :dim] + + +class LightConvEncoderLayer(nn.Module): + """Encoder layer block. + + Args: + args (argparse.Namespace): parsed command-line arguments + kernel_size: kernel size of the convolution + """ + + def __init__(self, args, kernel_size=0): + super().__init__() + self.embed_dim = args.encoder_embed_dim + self.conv_dim = args.encoder_conv_dim + padding_l = ( + kernel_size // 2 + if kernel_size % 2 == 1 + else ((kernel_size - 1) // 2, kernel_size // 2) + ) + + if args.encoder_glu: + self.linear1 = Linear(self.embed_dim, 2 * self.conv_dim) + self.act = nn.GLU() + else: + self.linear1 = Linear(self.embed_dim, self.conv_dim) + self.act = None + if args.encoder_conv_type == "lightweight": + self.conv = LightweightConv( + self.conv_dim, + kernel_size, + padding_l=padding_l, + weight_softmax=args.weight_softmax, + num_heads=args.encoder_attention_heads, + weight_dropout=args.weight_dropout, + ) + elif args.encoder_conv_type == "dynamic": + self.conv = DynamicConv( + self.conv_dim, + kernel_size, + padding_l=padding_l, + weight_softmax=args.weight_softmax, + num_heads=args.encoder_attention_heads, + weight_dropout=args.weight_dropout, + ) + else: + raise NotImplementedError + self.linear2 = Linear(self.conv_dim, self.embed_dim) + + self.dropout_module = FairseqDropout( + args.dropout, module_name=self.__class__.__name__ + ) + self.relu_dropout_module = FairseqDropout( + args.relu_dropout, module_name=self.__class__.__name__ + ) + self.input_dropout_module = FairseqDropout( + args.input_dropout, module_name=self.__class__.__name__ + ) + self.normalize_before = args.encoder_normalize_before + self.fc1 = Linear(self.embed_dim, args.encoder_ffn_embed_dim) + self.fc2 = Linear(args.encoder_ffn_embed_dim, self.embed_dim) + self.layer_norms = nn.ModuleList([LayerNorm(self.embed_dim) for _ in range(2)]) + + def forward(self, x, encoder_padding_mask): + """ + Args: + x (Tensor): input to the layer of shape `(seq_len, batch, embed_dim)` + encoder_padding_mask (ByteTensor): binary ByteTensor of shape + `(batch, src_len)` where padding elements are indicated by ``1``. + + Returns: + encoded output of shape `(batch, src_len, embed_dim)` + """ + residual = x + x = self.maybe_layer_norm(0, x, before=True) + x = self.input_dropout_module(x) + x = self.linear1(x) + if self.act is not None: + x = self.act(x) + if encoder_padding_mask is not None: + x = x.masked_fill(encoder_padding_mask.transpose(0, 1).unsqueeze(2), 0) + x = self.conv(x) + x = self.linear2(x) + x = self.dropout_module(x) + x = residual + x + x = self.maybe_layer_norm(0, x, after=True) + + residual = x + x = self.maybe_layer_norm(1, x, before=True) + x = F.relu(self.fc1(x)) + x = self.relu_dropout_module(x) + x = self.fc2(x) + x = self.dropout_module(x) + x = residual + x + x = self.maybe_layer_norm(1, x, after=True) + return x + + def maybe_layer_norm(self, i, x, before=False, after=False): + assert before ^ after + if after ^ self.normalize_before: + return self.layer_norms[i](x) + else: + return x + + def extra_repr(self): + return ( + "dropout={}, relu_dropout={}, input_dropout={}, normalize_before={}".format( + self.dropout_module.p, + self.relu_dropout_module.p, + self.input_dropout_module.p, + self.normalize_before, + ) + ) + + +class LightConvDecoderLayer(nn.Module): + """Decoder layer block. + + Args: + args (argparse.Namespace): parsed command-line arguments + no_encoder_attn (bool, optional): whether to attend to encoder outputs. + Default: ``False`` + kernel_size: kernel size of the convolution + """ + + def __init__(self, args, no_encoder_attn=False, kernel_size=0): + super().__init__() + self.embed_dim = args.decoder_embed_dim + self.conv_dim = args.decoder_conv_dim + if args.decoder_glu: + self.linear1 = Linear(self.embed_dim, 2 * self.conv_dim) + self.act = nn.GLU() + else: + self.linear1 = Linear(self.embed_dim, self.conv_dim) + self.act = None + if args.decoder_conv_type == "lightweight": + self.conv = LightweightConv( + self.conv_dim, + kernel_size, + padding_l=kernel_size - 1, + weight_softmax=args.weight_softmax, + num_heads=args.decoder_attention_heads, + weight_dropout=args.weight_dropout, + ) + elif args.decoder_conv_type == "dynamic": + self.conv = DynamicConv( + self.conv_dim, + kernel_size, + padding_l=kernel_size - 1, + weight_softmax=args.weight_softmax, + num_heads=args.decoder_attention_heads, + weight_dropout=args.weight_dropout, + ) + else: + raise NotImplementedError + self.linear2 = Linear(self.conv_dim, self.embed_dim) + + self.dropout_module = FairseqDropout( + args.dropout, module_name=self.__class__.__name__ + ) + self.relu_dropout_module = FairseqDropout( + args.relu_dropout, module_name=self.__class__.__name__ + ) + self.input_dropout_module = FairseqDropout( + args.input_dropout, module_name=self.__class__.__name__ + ) + self.normalize_before = args.decoder_normalize_before + + self.conv_layer_norm = LayerNorm(self.embed_dim) + + if no_encoder_attn: + self.encoder_attn = None + self.encoder_attn_layer_norm = None + else: + self.encoder_attn = MultiheadAttention( + self.embed_dim, + args.decoder_attention_heads, + dropout=args.attention_dropout, + encoder_decoder_attention=True, + ) + self.encoder_attn_layer_norm = LayerNorm(self.embed_dim) + + self.fc1 = Linear(self.embed_dim, args.decoder_ffn_embed_dim) + self.fc2 = Linear(args.decoder_ffn_embed_dim, self.embed_dim) + + self.final_layer_norm = LayerNorm(self.embed_dim) + self.need_attn = True + + def forward( + self, + x, + encoder_out, + encoder_padding_mask, + incremental_state, + prev_conv_state=None, + prev_attn_state=None, + conv_mask=None, + conv_padding_mask=None, + ): + """ + Args: + x (Tensor): input to the layer of shape `(seq_len, batch, embed_dim)` + encoder_padding_mask (ByteTensor): binary ByteTensor of shape + `(batch, src_len)` where padding elements are indicated by ``1``. + + Returns: + encoded output of shape `(batch, src_len, embed_dim)` + """ + residual = x + x = self.maybe_layer_norm(self.conv_layer_norm, x, before=True) + if prev_conv_state is not None: + if incremental_state is None: + incremental_state = {} + self.conv._set_input_buffer(incremental_state, prev_conv_state) + x = self.input_dropout_module(x) + x = self.linear1(x) + if self.act is not None: + x = self.act(x) + x = self.conv(x, incremental_state=incremental_state) + x = self.linear2(x) + x = self.dropout_module(x) + x = residual + x + x = self.maybe_layer_norm(self.conv_layer_norm, x, after=True) + + attn = None + if self.encoder_attn is not None: + residual = x + x = self.maybe_layer_norm(self.encoder_attn_layer_norm, x, before=True) + if prev_attn_state is not None: + if incremental_state is None: + incremental_state = {} + prev_key, prev_value = prev_attn_state + saved_state = {"prev_key": prev_key, "prev_value": prev_value} + self.encoder_attn._set_input_buffer(incremental_state, saved_state) + x, attn = self.encoder_attn( + query=x, + key=encoder_out, + value=encoder_out, + key_padding_mask=encoder_padding_mask, + incremental_state=incremental_state, + static_kv=True, + need_weights=(not self.training and self.need_attn), + ) + x = self.dropout_module(x) + x = residual + x + x = self.maybe_layer_norm(self.encoder_attn_layer_norm, x, after=True) + + residual = x + x = self.maybe_layer_norm(self.final_layer_norm, x, before=True) + x = F.relu(self.fc1(x)) + x = self.relu_dropout_module(x) + x = self.fc2(x) + x = self.dropout_module(x) + x = residual + x + x = self.maybe_layer_norm(self.final_layer_norm, x, after=True) + return x, attn + + def maybe_layer_norm(self, layer_norm, x, before=False, after=False): + assert before ^ after + if after ^ self.normalize_before: + return layer_norm(x) + else: + return x + + def make_generation_fast_(self, need_attn=False, **kwargs): + self.need_attn = need_attn + + def extra_repr(self): + return ( + "dropout={}, relu_dropout={}, input_dropout={}, normalize_before={}".format( + self.dropout_module.p, + self.relu_dropout_module.p, + self.input_dropout_module.p, + self.normalize_before, + ) + ) + + +def Embedding(num_embeddings, embedding_dim, padding_idx): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + nn.init.normal_(m.weight, mean=0, std=embedding_dim**-0.5) + nn.init.constant_(m.weight[padding_idx], 0) + return m + + +def Linear(in_features, out_features, bias=True): + m = nn.Linear(in_features, out_features, bias) + nn.init.xavier_uniform_(m.weight) + if bias: + nn.init.constant_(m.bias, 0.0) + return m + + +@register_model_architecture("lightconv", "lightconv") +def base_architecture(args): + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 7) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", False) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.relu_dropout = getattr(args, "relu_dropout", 0.0) + args.dropout = getattr(args, "dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", False) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + args.encoder_conv_dim = getattr(args, "encoder_conv_dim", args.encoder_embed_dim) + args.decoder_conv_dim = getattr(args, "decoder_conv_dim", args.decoder_embed_dim) + + args.encoder_kernel_size_list = getattr( + args, "encoder_kernel_size_list", [3, 7, 15, 31, 31, 31, 31] + ) + args.decoder_kernel_size_list = getattr( + args, "decoder_kernel_size_list", [3, 7, 15, 31, 31, 31] + ) + if len(args.encoder_kernel_size_list) == 1: + args.encoder_kernel_size_list = ( + args.encoder_kernel_size_list * args.encoder_layers + ) + if len(args.decoder_kernel_size_list) == 1: + args.decoder_kernel_size_list = ( + args.decoder_kernel_size_list * args.decoder_layers + ) + assert ( + len(args.encoder_kernel_size_list) == args.encoder_layers + ), "encoder_kernel_size_list doesn't match encoder_layers" + assert ( + len(args.decoder_kernel_size_list) == args.decoder_layers + ), "decoder_kernel_size_list doesn't match decoder_layers" + args.encoder_glu = getattr(args, "encoder_glu", True) + args.decoder_glu = getattr(args, "decoder_glu", True) + args.input_dropout = getattr(args, "input_dropout", 0.1) + args.weight_dropout = getattr(args, "weight_dropout", args.attention_dropout) + + +@register_model_architecture("lightconv", "lightconv_iwslt_de_en") +def lightconv_iwslt_de_en(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 1024) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.encoder_layers = getattr(args, "encoder_layers", 7) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 1024) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 4) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.weight_dropout = getattr(args, "weight_dropout", 0.1) + args.encoder_glu = getattr(args, "encoder_glu", False) + args.decoder_glu = getattr(args, "decoder_glu", False) + args.input_dropout = getattr(args, "input_dropout", 0.0) + base_architecture(args) + + +@register_model_architecture("lightconv", "lightconv_wmt_en_de") +def lightconv_wmt_en_de(args): + base_architecture(args) + + +@register_model_architecture("lightconv", "lightconv_wmt_en_de_big") +def lightconv_wmt_en_de_big(args): + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4096) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 16) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 1024) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 4096) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 16) + args.dropout = getattr(args, "dropout", 0.3) + base_architecture(args) + + +@register_model_architecture("lightconv", "lightconv_wmt_en_fr_big") +def lightconv_wmt_en_fr_big(args): + args.dropout = getattr(args, "dropout", 0.1) + lightconv_wmt_en_de_big(args) + + +@register_model_architecture("lightconv", "lightconv_wmt_zh_en_big") +def lightconv_wmt_zh_en_big(args): + args.dropout = getattr(args, "dropout", 0.2) + args.attention_dropout = getattr(args, "attention_dropout", 0.2) + args.weight_dropout = getattr(args, "weight_dropout", 0.2) + lightconv_wmt_en_de_big(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/lightconv_lm.py b/PyTorch/NLP/new-Transformer/fairseq/models/lightconv_lm.py new file mode 100644 index 00000000..1d9efc4e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/lightconv_lm.py @@ -0,0 +1,306 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq import utils +from fairseq.models import ( + FairseqLanguageModel, + register_model, + register_model_architecture, +) +from fairseq.models.lightconv import Embedding, LightConvDecoder +from fairseq.modules import AdaptiveInput, CharacterTokenEmbedder + + +@register_model("lightconv_lm") +class LightConvLanguageModel(FairseqLanguageModel): + def __init__(self, decoder): + super().__init__(decoder) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + parser.add_argument( + "--dropout", + default=0.1, + type=float, + metavar="D", + help="dropout probability", + ) + parser.add_argument( + "--attention-dropout", + default=0.0, + type=float, + metavar="D", + help="dropout probability for attention weights", + ) + parser.add_argument( + "--relu-dropout", + default=0.0, + type=float, + metavar="D", + help="dropout probability after ReLU in FFN", + ) + parser.add_argument( + "--input-dropout", + type=float, + metavar="D", + help="dropout probability of the inputs", + ) + parser.add_argument( + "--decoder-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension", + ) + parser.add_argument( + "--decoder-output-dim", + type=int, + metavar="N", + help="decoder output dimension", + ) + parser.add_argument( + "--decoder-input-dim", type=int, metavar="N", help="decoder input dimension" + ) + parser.add_argument( + "--decoder-ffn-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension for FFN", + ) + parser.add_argument( + "--decoder-layers", type=int, metavar="N", help="num decoder layers" + ) + parser.add_argument( + "--decoder-attention-heads", + type=int, + metavar="N", + help="num decoder attention heads or LightConv/DynamicConv heads", + ) + parser.add_argument( + "--decoder-normalize-before", + default=False, + action="store_true", + help="apply layernorm before each decoder block", + ) + parser.add_argument( + "--adaptive-softmax-cutoff", + metavar="EXPR", + help="comma separated list of adaptive softmax cutoff points. " + "Must be used with adaptive_loss criterion", + ) + parser.add_argument( + "--adaptive-softmax-dropout", + type=float, + metavar="D", + help="sets adaptive softmax dropout for the tail projections", + ) + parser.add_argument( + "--adaptive-softmax-factor", + type=float, + metavar="N", + help="adaptive input factor", + ) + parser.add_argument( + "--no-token-positional-embeddings", + default=False, + action="store_true", + help="if set, disables positional embeddings (outside self attention)", + ) + parser.add_argument( + "--share-decoder-input-output-embed", + default=False, + action="store_true", + help="share decoder input and output embeddings", + ) + parser.add_argument( + "--character-embeddings", + default=False, + action="store_true", + help="if set, uses character embedding convolutions to produce token embeddings", + ) + parser.add_argument( + "--character-filters", + type=str, + metavar="LIST", + default="[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]", + help="size of character embeddings", + ) + parser.add_argument( + "--character-embedding-dim", + type=int, + metavar="N", + default=4, + help="size of character embeddings", + ) + parser.add_argument( + "--char-embedder-highway-layers", + type=int, + metavar="N", + default=2, + help="number of highway layers for character token embeddder", + ) + parser.add_argument( + "--adaptive-input", + default=False, + action="store_true", + help="if set, uses adaptive input", + ) + parser.add_argument( + "--adaptive-input-factor", + type=float, + metavar="N", + help="adaptive input factor", + ) + parser.add_argument( + "--adaptive-input-cutoff", + metavar="EXPR", + help="comma separated list of adaptive input cutoff points.", + ) + parser.add_argument( + "--tie-adaptive-weights", + action="store_true", + help="if set, ties the weights of adaptive softmax and adaptive input", + ) + parser.add_argument( + "--tie-adaptive-proj", + action="store_true", + help="if set, ties the projection weights of adaptive softmax and adaptive input", + ) + parser.add_argument( + "--decoder-learned-pos", + action="store_true", + help="use learned positional embeddings in the decoder", + ) + + """LightConv and DynamicConv arguments""" + parser.add_argument( + "--decoder-kernel-size-list", + type=lambda x: utils.eval_str_list(x, int), + help='list of kernel size (default: "[3,7,15,31,31,31]")', + ) + parser.add_argument( + "--decoder-glu", type=utils.eval_bool, help="glu after in proj" + ) + parser.add_argument( + "--decoder-conv-type", + default="dynamic", + type=str, + choices=["dynamic", "lightweight"], + help="type of convolution", + ) + parser.add_argument("--weight-softmax", default=True, type=utils.eval_bool) + parser.add_argument( + "--weight-dropout", + type=float, + metavar="D", + help="dropout probability for conv weights", + ) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present in older models + base_lm_architecture(args) + + if getattr(args, "max_source_positions", None) is None: + args.max_source_positions = args.tokens_per_sample + if getattr(args, "max_target_positions", None) is None: + args.max_target_positions = args.tokens_per_sample + + if args.character_embeddings: + embed_tokens = CharacterTokenEmbedder( + task.dictionary, + eval(args.character_filters), + args.character_embedding_dim, + args.decoder_embed_dim, + args.char_embedder_highway_layers, + ) + elif args.adaptive_input: + embed_tokens = AdaptiveInput( + len(task.dictionary), + task.dictionary.pad(), + args.decoder_input_dim, + args.adaptive_input_factor, + args.decoder_embed_dim, + utils.eval_str_list(args.adaptive_input_cutoff, type=int), + ) + else: + embed_tokens = Embedding( + len(task.dictionary), args.decoder_input_dim, task.dictionary.pad() + ) + + if args.tie_adaptive_weights: + assert args.adaptive_input + assert args.adaptive_input_factor == args.adaptive_softmax_factor + assert ( + args.adaptive_softmax_cutoff == args.adaptive_input_cutoff + ), "{} != {}".format( + args.adaptive_softmax_cutoff, args.adaptive_input_cutoff + ) + assert args.decoder_input_dim == args.decoder_output_dim + + decoder = LightConvDecoder( + args, + task.output_dictionary, + embed_tokens, + no_encoder_attn=True, + final_norm=False, + ) + return LightConvLanguageModel(decoder) + + +@register_model_architecture("lightconv_lm", "lightconv_lm") +def base_lm_architecture(args): + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 2048) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.adaptive_softmax_factor = getattr(args, "adaptive_softmax_factor", 4) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + + args.character_embeddings = getattr(args, "character_embeddings", False) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + args.decoder_conv_dim = getattr(args, "decoder_conv_dim", args.decoder_embed_dim) + + # The model training is not stable without this + args.decoder_normalize_before = True + + args.adaptive_input = getattr(args, "adaptive_input", False) + args.adaptive_input_factor = getattr(args, "adaptive_input_factor", 4) + args.adaptive_input_cutoff = getattr(args, "adaptive_input_cutoff", None) + + args.tie_adaptive_weights = getattr(args, "tie_adaptive_weights", False) + args.tie_adaptive_proj = getattr(args, "tie_adaptive_proj", False) + + args.decoder_kernel_size_list = getattr( + args, "decoder_kernel_size_list", [3, 7, 15, 31, 31, 31] + ) + if len(args.decoder_kernel_size_list) == 1: + args.decoder_kernel_size_list = ( + args.decoder_kernel_size_list * args.decoder_layers + ) + assert ( + len(args.decoder_kernel_size_list) == args.decoder_layers + ), "decoder_kernel_size_list doesn't match decoder_layers" + args.decoder_glu = getattr(args, "decoder_glu", True) + args.input_dropout = getattr(args, "input_dropout", 0.1) + args.weight_dropout = getattr(args, "weight_dropout", args.attention_dropout) + + +@register_model_architecture("lightconv_lm", "lightconv_lm_gbw") +def lightconv_lm_gbw(args): + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 4096) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 16) + base_lm_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/lstm.py b/PyTorch/NLP/new-Transformer/fairseq/models/lstm.py new file mode 100644 index 00000000..8a291562 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/lstm.py @@ -0,0 +1,755 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Dict, List, Optional, Tuple + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + FairseqIncrementalDecoder, + register_model, + register_model_architecture, +) +from fairseq.modules import AdaptiveSoftmax, FairseqDropout +from torch import Tensor + + +DEFAULT_MAX_SOURCE_POSITIONS = 1e5 +DEFAULT_MAX_TARGET_POSITIONS = 1e5 + + +@register_model("lstm") +class LSTMModel(FairseqEncoderDecoderModel): + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--dropout', type=float, metavar='D', + help='dropout probability') + parser.add_argument('--encoder-embed-dim', type=int, metavar='N', + help='encoder embedding dimension') + parser.add_argument('--encoder-embed-path', type=str, metavar='STR', + help='path to pre-trained encoder embedding') + parser.add_argument('--encoder-freeze-embed', action='store_true', + help='freeze encoder embeddings') + parser.add_argument('--encoder-hidden-size', type=int, metavar='N', + help='encoder hidden size') + parser.add_argument('--encoder-layers', type=int, metavar='N', + help='number of encoder layers') + parser.add_argument('--encoder-bidirectional', action='store_true', + help='make all layers of encoder bidirectional') + parser.add_argument('--decoder-embed-dim', type=int, metavar='N', + help='decoder embedding dimension') + parser.add_argument('--decoder-embed-path', type=str, metavar='STR', + help='path to pre-trained decoder embedding') + parser.add_argument('--decoder-freeze-embed', action='store_true', + help='freeze decoder embeddings') + parser.add_argument('--decoder-hidden-size', type=int, metavar='N', + help='decoder hidden size') + parser.add_argument('--decoder-layers', type=int, metavar='N', + help='number of decoder layers') + parser.add_argument('--decoder-out-embed-dim', type=int, metavar='N', + help='decoder output embedding dimension') + parser.add_argument('--decoder-attention', type=str, metavar='BOOL', + help='decoder attention') + parser.add_argument('--adaptive-softmax-cutoff', metavar='EXPR', + help='comma separated list of adaptive softmax cutoff points. ' + 'Must be used with adaptive_loss criterion') + parser.add_argument('--share-decoder-input-output-embed', default=False, + action='store_true', + help='share decoder input and output embeddings') + parser.add_argument('--share-all-embeddings', default=False, action='store_true', + help='share encoder, decoder and output embeddings' + ' (requires shared dictionary and embed dim)') + + # Granular dropout settings (if not specified these default to --dropout) + parser.add_argument('--encoder-dropout-in', type=float, metavar='D', + help='dropout probability for encoder input embedding') + parser.add_argument('--encoder-dropout-out', type=float, metavar='D', + help='dropout probability for encoder output') + parser.add_argument('--decoder-dropout-in', type=float, metavar='D', + help='dropout probability for decoder input embedding') + parser.add_argument('--decoder-dropout-out', type=float, metavar='D', + help='dropout probability for decoder output') + # fmt: on + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + # make sure that all args are properly defaulted (in case there are any new ones) + base_architecture(args) + + if args.encoder_layers != args.decoder_layers: + raise ValueError("--encoder-layers must match --decoder-layers") + + max_source_positions = getattr( + args, "max_source_positions", DEFAULT_MAX_SOURCE_POSITIONS + ) + max_target_positions = getattr( + args, "max_target_positions", DEFAULT_MAX_TARGET_POSITIONS + ) + + def load_pretrained_embedding_from_file(embed_path, dictionary, embed_dim): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + embed_tokens = Embedding(num_embeddings, embed_dim, padding_idx) + embed_dict = utils.parse_embedding(embed_path) + utils.print_embed_overlap(embed_dict, dictionary) + return utils.load_embedding(embed_dict, dictionary, embed_tokens) + + if args.encoder_embed_path: + pretrained_encoder_embed = load_pretrained_embedding_from_file( + args.encoder_embed_path, task.source_dictionary, args.encoder_embed_dim + ) + else: + num_embeddings = len(task.source_dictionary) + pretrained_encoder_embed = Embedding( + num_embeddings, args.encoder_embed_dim, task.source_dictionary.pad() + ) + + if args.share_all_embeddings: + # double check all parameters combinations are valid + if task.source_dictionary != task.target_dictionary: + raise ValueError("--share-all-embeddings requires a joint dictionary") + if args.decoder_embed_path and ( + args.decoder_embed_path != args.encoder_embed_path + ): + raise ValueError( + "--share-all-embed not compatible with --decoder-embed-path" + ) + if args.encoder_embed_dim != args.decoder_embed_dim: + raise ValueError( + "--share-all-embeddings requires --encoder-embed-dim to " + "match --decoder-embed-dim" + ) + pretrained_decoder_embed = pretrained_encoder_embed + args.share_decoder_input_output_embed = True + else: + # separate decoder input embeddings + pretrained_decoder_embed = None + if args.decoder_embed_path: + pretrained_decoder_embed = load_pretrained_embedding_from_file( + args.decoder_embed_path, + task.target_dictionary, + args.decoder_embed_dim, + ) + # one last double check of parameter combinations + if args.share_decoder_input_output_embed and ( + args.decoder_embed_dim != args.decoder_out_embed_dim + ): + raise ValueError( + "--share-decoder-input-output-embeddings requires " + "--decoder-embed-dim to match --decoder-out-embed-dim" + ) + + if args.encoder_freeze_embed: + pretrained_encoder_embed.weight.requires_grad = False + if args.decoder_freeze_embed: + pretrained_decoder_embed.weight.requires_grad = False + + encoder = LSTMEncoder( + dictionary=task.source_dictionary, + embed_dim=args.encoder_embed_dim, + hidden_size=args.encoder_hidden_size, + num_layers=args.encoder_layers, + dropout_in=args.encoder_dropout_in, + dropout_out=args.encoder_dropout_out, + bidirectional=args.encoder_bidirectional, + pretrained_embed=pretrained_encoder_embed, + max_source_positions=max_source_positions, + ) + decoder = LSTMDecoder( + dictionary=task.target_dictionary, + embed_dim=args.decoder_embed_dim, + hidden_size=args.decoder_hidden_size, + out_embed_dim=args.decoder_out_embed_dim, + num_layers=args.decoder_layers, + dropout_in=args.decoder_dropout_in, + dropout_out=args.decoder_dropout_out, + attention=utils.eval_bool(args.decoder_attention), + encoder_output_units=encoder.output_units, + pretrained_embed=pretrained_decoder_embed, + share_input_output_embed=args.share_decoder_input_output_embed, + adaptive_softmax_cutoff=( + utils.eval_str_list(args.adaptive_softmax_cutoff, type=int) + if args.criterion == "adaptive_loss" + else None + ), + max_target_positions=max_target_positions, + residuals=False, + ) + return cls(encoder, decoder) + + def forward( + self, + src_tokens, + src_lengths, + prev_output_tokens, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + ): + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths) + decoder_out = self.decoder( + prev_output_tokens, + encoder_out=encoder_out, + incremental_state=incremental_state, + ) + return decoder_out + + +class LSTMEncoder(FairseqEncoder): + """LSTM encoder.""" + + def __init__( + self, + dictionary, + embed_dim=512, + hidden_size=512, + num_layers=1, + dropout_in=0.1, + dropout_out=0.1, + bidirectional=False, + left_pad=True, + pretrained_embed=None, + padding_idx=None, + max_source_positions=DEFAULT_MAX_SOURCE_POSITIONS, + ): + super().__init__(dictionary) + self.num_layers = num_layers + self.dropout_in_module = FairseqDropout( + dropout_in * 1.0, module_name=self.__class__.__name__ + ) + self.dropout_out_module = FairseqDropout( + dropout_out * 1.0, module_name=self.__class__.__name__ + ) + self.bidirectional = bidirectional + self.hidden_size = hidden_size + self.max_source_positions = max_source_positions + + num_embeddings = len(dictionary) + self.padding_idx = padding_idx if padding_idx is not None else dictionary.pad() + if pretrained_embed is None: + self.embed_tokens = Embedding(num_embeddings, embed_dim, self.padding_idx) + else: + self.embed_tokens = pretrained_embed + + self.lstm = LSTM( + input_size=embed_dim, + hidden_size=hidden_size, + num_layers=num_layers, + dropout=self.dropout_out_module.p if num_layers > 1 else 0.0, + bidirectional=bidirectional, + ) + self.left_pad = left_pad + + self.output_units = hidden_size + if bidirectional: + self.output_units *= 2 + + def forward( + self, + src_tokens: Tensor, + src_lengths: Tensor, + enforce_sorted: bool = True, + ): + """ + Args: + src_tokens (LongTensor): tokens in the source language of + shape `(batch, src_len)` + src_lengths (LongTensor): lengths of each source sentence of + shape `(batch)` + enforce_sorted (bool, optional): if True, `src_tokens` is + expected to contain sequences sorted by length in a + decreasing order. If False, this condition is not + required. Default: True. + """ + if self.left_pad: + # nn.utils.rnn.pack_padded_sequence requires right-padding; + # convert left-padding to right-padding + src_tokens = utils.convert_padding_direction( + src_tokens, + torch.zeros_like(src_tokens).fill_(self.padding_idx), + left_to_right=True, + ) + + bsz, seqlen = src_tokens.size() + + # embed tokens + x = self.embed_tokens(src_tokens) + x = self.dropout_in_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + # pack embedded source tokens into a PackedSequence + packed_x = nn.utils.rnn.pack_padded_sequence( + x, src_lengths.cpu(), enforce_sorted=enforce_sorted + ) + + # apply LSTM + if self.bidirectional: + state_size = 2 * self.num_layers, bsz, self.hidden_size + else: + state_size = self.num_layers, bsz, self.hidden_size + h0 = x.new_zeros(*state_size) + c0 = x.new_zeros(*state_size) + packed_outs, (final_hiddens, final_cells) = self.lstm(packed_x, (h0, c0)) + + # unpack outputs and apply dropout + x, _ = nn.utils.rnn.pad_packed_sequence( + packed_outs, padding_value=self.padding_idx * 1.0 + ) + x = self.dropout_out_module(x) + assert list(x.size()) == [seqlen, bsz, self.output_units] + + if self.bidirectional: + final_hiddens = self.combine_bidir(final_hiddens, bsz) + final_cells = self.combine_bidir(final_cells, bsz) + + encoder_padding_mask = src_tokens.eq(self.padding_idx).t() + + return tuple( + ( + x, # seq_len x batch x hidden + final_hiddens, # num_layers x batch x num_directions*hidden + final_cells, # num_layers x batch x num_directions*hidden + encoder_padding_mask, # seq_len x batch + ) + ) + + def combine_bidir(self, outs, bsz: int): + out = outs.view(self.num_layers, 2, bsz, -1).transpose(1, 2).contiguous() + return out.view(self.num_layers, bsz, -1) + + def reorder_encoder_out( + self, encoder_out: Tuple[Tensor, Tensor, Tensor, Tensor], new_order + ): + return tuple( + ( + encoder_out[0].index_select(1, new_order), + encoder_out[1].index_select(1, new_order), + encoder_out[2].index_select(1, new_order), + encoder_out[3].index_select(1, new_order), + ) + ) + + def max_positions(self): + """Maximum input length supported by the encoder.""" + return self.max_source_positions + + +class AttentionLayer(nn.Module): + def __init__(self, input_embed_dim, source_embed_dim, output_embed_dim, bias=False): + super().__init__() + + self.input_proj = Linear(input_embed_dim, source_embed_dim, bias=bias) + self.output_proj = Linear( + input_embed_dim + source_embed_dim, output_embed_dim, bias=bias + ) + + def forward(self, input, source_hids, encoder_padding_mask): + # input: bsz x input_embed_dim + # source_hids: srclen x bsz x source_embed_dim + + # x: bsz x source_embed_dim + x = self.input_proj(input) + + # compute attention + attn_scores = (source_hids * x.unsqueeze(0)).sum(dim=2) + + # don't attend over padding + if encoder_padding_mask is not None: + attn_scores = ( + attn_scores.float() + .masked_fill_(encoder_padding_mask, float("-inf")) + .type_as(attn_scores) + ) # FP16 support: cast to float and back + + attn_scores = F.softmax(attn_scores, dim=0) # srclen x bsz + + # sum weighted sources + x = (attn_scores.unsqueeze(2) * source_hids).sum(dim=0) + + x = torch.tanh(self.output_proj(torch.cat((x, input), dim=1))) + return x, attn_scores + + +class LSTMDecoder(FairseqIncrementalDecoder): + """LSTM decoder.""" + + def __init__( + self, + dictionary, + embed_dim=512, + hidden_size=512, + out_embed_dim=512, + num_layers=1, + dropout_in=0.1, + dropout_out=0.1, + attention=True, + encoder_output_units=512, + pretrained_embed=None, + share_input_output_embed=False, + adaptive_softmax_cutoff=None, + max_target_positions=DEFAULT_MAX_TARGET_POSITIONS, + residuals=False, + ): + super().__init__(dictionary) + self.dropout_in_module = FairseqDropout( + dropout_in * 1.0, module_name=self.__class__.__name__ + ) + self.dropout_out_module = FairseqDropout( + dropout_out * 1.0, module_name=self.__class__.__name__ + ) + self.hidden_size = hidden_size + self.share_input_output_embed = share_input_output_embed + self.need_attn = True + self.max_target_positions = max_target_positions + self.residuals = residuals + self.num_layers = num_layers + + self.adaptive_softmax = None + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + if pretrained_embed is None: + self.embed_tokens = Embedding(num_embeddings, embed_dim, padding_idx) + else: + self.embed_tokens = pretrained_embed + + self.encoder_output_units = encoder_output_units + if encoder_output_units != hidden_size and encoder_output_units != 0: + self.encoder_hidden_proj = Linear(encoder_output_units, hidden_size) + self.encoder_cell_proj = Linear(encoder_output_units, hidden_size) + else: + self.encoder_hidden_proj = self.encoder_cell_proj = None + + # disable input feeding if there is no encoder + # input feeding is described in arxiv.org/abs/1508.04025 + input_feed_size = 0 if encoder_output_units == 0 else hidden_size + self.layers = nn.ModuleList( + [ + LSTMCell( + input_size=input_feed_size + embed_dim + if layer == 0 + else hidden_size, + hidden_size=hidden_size, + ) + for layer in range(num_layers) + ] + ) + + if attention: + # TODO make bias configurable + self.attention = AttentionLayer( + hidden_size, encoder_output_units, hidden_size, bias=False + ) + else: + self.attention = None + + if hidden_size != out_embed_dim: + self.additional_fc = Linear(hidden_size, out_embed_dim) + + if adaptive_softmax_cutoff is not None: + # setting adaptive_softmax dropout to dropout_out for now but can be redefined + self.adaptive_softmax = AdaptiveSoftmax( + num_embeddings, + hidden_size, + adaptive_softmax_cutoff, + dropout=dropout_out, + ) + elif not self.share_input_output_embed: + self.fc_out = Linear(out_embed_dim, num_embeddings, dropout=dropout_out) + + def forward( + self, + prev_output_tokens, + encoder_out: Optional[Tuple[Tensor, Tensor, Tensor, Tensor]] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + src_lengths: Optional[Tensor] = None, + ): + x, attn_scores = self.extract_features( + prev_output_tokens, encoder_out, incremental_state + ) + return self.output_layer(x), attn_scores + + def extract_features( + self, + prev_output_tokens, + encoder_out: Optional[Tuple[Tensor, Tensor, Tensor, Tensor]] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + ): + """ + Similar to *forward* but only return features. + """ + # get outputs from encoder + if encoder_out is not None: + encoder_outs = encoder_out[0] + encoder_hiddens = encoder_out[1] + encoder_cells = encoder_out[2] + encoder_padding_mask = encoder_out[3] + else: + encoder_outs = torch.empty(0) + encoder_hiddens = torch.empty(0) + encoder_cells = torch.empty(0) + encoder_padding_mask = torch.empty(0) + srclen = encoder_outs.size(0) + + if incremental_state is not None and len(incremental_state) > 0: + prev_output_tokens = prev_output_tokens[:, -1:] + + bsz, seqlen = prev_output_tokens.size() + + # embed tokens + x = self.embed_tokens(prev_output_tokens) + x = self.dropout_in_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + # initialize previous states (or get from cache during incremental generation) + if incremental_state is not None and len(incremental_state) > 0: + prev_hiddens, prev_cells, input_feed = self.get_cached_state( + incremental_state + ) + elif encoder_out is not None: + # setup recurrent cells + prev_hiddens = [encoder_hiddens[i] for i in range(self.num_layers)] + prev_cells = [encoder_cells[i] for i in range(self.num_layers)] + if self.encoder_hidden_proj is not None: + prev_hiddens = [self.encoder_hidden_proj(y) for y in prev_hiddens] + prev_cells = [self.encoder_cell_proj(y) for y in prev_cells] + input_feed = x.new_zeros(bsz, self.hidden_size) + else: + # setup zero cells, since there is no encoder + zero_state = x.new_zeros(bsz, self.hidden_size) + prev_hiddens = [zero_state for i in range(self.num_layers)] + prev_cells = [zero_state for i in range(self.num_layers)] + input_feed = None + + assert ( + srclen > 0 or self.attention is None + ), "attention is not supported if there are no encoder outputs" + attn_scores: Optional[Tensor] = ( + x.new_zeros(srclen, seqlen, bsz) if self.attention is not None else None + ) + outs = [] + for j in range(seqlen): + # input feeding: concatenate context vector from previous time step + if input_feed is not None: + input = torch.cat((x[j, :, :], input_feed), dim=1) + else: + input = x[j] + + for i, rnn in enumerate(self.layers): + # recurrent cell + hidden, cell = rnn(input, (prev_hiddens[i], prev_cells[i])) + + # hidden state becomes the input to the next layer + input = self.dropout_out_module(hidden) + if self.residuals: + input = input + prev_hiddens[i] + + # save state for next time step + prev_hiddens[i] = hidden + prev_cells[i] = cell + + # apply attention using the last layer's hidden state + if self.attention is not None: + assert attn_scores is not None + out, attn_scores[:, j, :] = self.attention( + hidden, encoder_outs, encoder_padding_mask + ) + else: + out = hidden + out = self.dropout_out_module(out) + + # input feeding + if input_feed is not None: + input_feed = out + + # save final output + outs.append(out) + + # Stack all the necessary tensors together and store + prev_hiddens_tensor = torch.stack(prev_hiddens) + prev_cells_tensor = torch.stack(prev_cells) + cache_state = torch.jit.annotate( + Dict[str, Optional[Tensor]], + { + "prev_hiddens": prev_hiddens_tensor, + "prev_cells": prev_cells_tensor, + "input_feed": input_feed, + }, + ) + self.set_incremental_state(incremental_state, "cached_state", cache_state) + + # collect outputs across time steps + x = torch.cat(outs, dim=0).view(seqlen, bsz, self.hidden_size) + + # T x B x C -> B x T x C + x = x.transpose(1, 0) + + if hasattr(self, "additional_fc") and self.adaptive_softmax is None: + x = self.additional_fc(x) + x = self.dropout_out_module(x) + # srclen x tgtlen x bsz -> bsz x tgtlen x srclen + if not self.training and self.need_attn and self.attention is not None: + assert attn_scores is not None + attn_scores = attn_scores.transpose(0, 2) + else: + attn_scores = None + return x, attn_scores + + def output_layer(self, x): + """Project features to the vocabulary size.""" + if self.adaptive_softmax is None: + if self.share_input_output_embed: + x = F.linear(x, self.embed_tokens.weight) + else: + x = self.fc_out(x) + return x + + def get_cached_state( + self, + incremental_state: Dict[str, Dict[str, Optional[Tensor]]], + ) -> Tuple[List[Tensor], List[Tensor], Optional[Tensor]]: + cached_state = self.get_incremental_state(incremental_state, "cached_state") + assert cached_state is not None + prev_hiddens_ = cached_state["prev_hiddens"] + assert prev_hiddens_ is not None + prev_cells_ = cached_state["prev_cells"] + assert prev_cells_ is not None + prev_hiddens = [prev_hiddens_[i] for i in range(self.num_layers)] + prev_cells = [prev_cells_[j] for j in range(self.num_layers)] + input_feed = cached_state[ + "input_feed" + ] # can be None for decoder-only language models + return prev_hiddens, prev_cells, input_feed + + def reorder_incremental_state( + self, + incremental_state: Dict[str, Dict[str, Optional[Tensor]]], + new_order: Tensor, + ): + if incremental_state is None or len(incremental_state) == 0: + return + prev_hiddens, prev_cells, input_feed = self.get_cached_state(incremental_state) + prev_hiddens = [p.index_select(0, new_order) for p in prev_hiddens] + prev_cells = [p.index_select(0, new_order) for p in prev_cells] + if input_feed is not None: + input_feed = input_feed.index_select(0, new_order) + cached_state_new = torch.jit.annotate( + Dict[str, Optional[Tensor]], + { + "prev_hiddens": torch.stack(prev_hiddens), + "prev_cells": torch.stack(prev_cells), + "input_feed": input_feed, + }, + ) + self.set_incremental_state(incremental_state, "cached_state", cached_state_new), + return + + def max_positions(self): + """Maximum output length supported by the decoder.""" + return self.max_target_positions + + def make_generation_fast_(self, need_attn=False, **kwargs): + self.need_attn = need_attn + + +def Embedding(num_embeddings, embedding_dim, padding_idx): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + nn.init.uniform_(m.weight, -0.1, 0.1) + nn.init.constant_(m.weight[padding_idx], 0) + return m + + +def LSTM(input_size, hidden_size, **kwargs): + m = nn.LSTM(input_size, hidden_size, **kwargs) + for name, param in m.named_parameters(): + if "weight" in name or "bias" in name: + param.data.uniform_(-0.1, 0.1) + return m + + +def LSTMCell(input_size, hidden_size, **kwargs): + m = nn.LSTMCell(input_size, hidden_size, **kwargs) + for name, param in m.named_parameters(): + if "weight" in name or "bias" in name: + param.data.uniform_(-0.1, 0.1) + return m + + +def Linear(in_features, out_features, bias=True, dropout=0.0): + """Linear layer (input: N x T x C)""" + m = nn.Linear(in_features, out_features, bias=bias) + m.weight.data.uniform_(-0.1, 0.1) + if bias: + m.bias.data.uniform_(-0.1, 0.1) + return m + + +@register_model_architecture("lstm", "lstm") +def base_architecture(args): + args.dropout = getattr(args, "dropout", 0.1) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_freeze_embed = getattr(args, "encoder_freeze_embed", False) + args.encoder_hidden_size = getattr( + args, "encoder_hidden_size", args.encoder_embed_dim + ) + args.encoder_layers = getattr(args, "encoder_layers", 1) + args.encoder_bidirectional = getattr(args, "encoder_bidirectional", False) + args.encoder_dropout_in = getattr(args, "encoder_dropout_in", args.dropout) + args.encoder_dropout_out = getattr(args, "encoder_dropout_out", args.dropout) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_freeze_embed = getattr(args, "decoder_freeze_embed", False) + args.decoder_hidden_size = getattr( + args, "decoder_hidden_size", args.decoder_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 1) + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 512) + args.decoder_attention = getattr(args, "decoder_attention", "1") + args.decoder_dropout_in = getattr(args, "decoder_dropout_in", args.dropout) + args.decoder_dropout_out = getattr(args, "decoder_dropout_out", args.dropout) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", False) + args.adaptive_softmax_cutoff = getattr( + args, "adaptive_softmax_cutoff", "10000,50000,200000" + ) + + +@register_model_architecture("lstm", "lstm_wiseman_iwslt_de_en") +def lstm_wiseman_iwslt_de_en(args): + args.dropout = getattr(args, "dropout", 0.1) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_dropout_in = getattr(args, "encoder_dropout_in", 0) + args.encoder_dropout_out = getattr(args, "encoder_dropout_out", 0) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 256) + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 256) + args.decoder_dropout_in = getattr(args, "decoder_dropout_in", 0) + args.decoder_dropout_out = getattr(args, "decoder_dropout_out", args.dropout) + base_architecture(args) + + +@register_model_architecture("lstm", "lstm_luong_wmt_en_de") +def lstm_luong_wmt_en_de(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1000) + args.encoder_layers = getattr(args, "encoder_layers", 4) + args.encoder_dropout_out = getattr(args, "encoder_dropout_out", 0) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 1000) + args.decoder_layers = getattr(args, "decoder_layers", 4) + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 1000) + args.decoder_dropout_out = getattr(args, "decoder_dropout_out", 0) + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/lstm_lm.py b/PyTorch/NLP/new-Transformer/fairseq/models/lstm_lm.py new file mode 100644 index 00000000..454f0ac3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/lstm_lm.py @@ -0,0 +1,142 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq import utils +from fairseq.models import ( + FairseqLanguageModel, + register_model, + register_model_architecture, +) +from fairseq.models.lstm import Embedding, LSTMDecoder + + +DEFAULT_MAX_TARGET_POSITIONS = 1e5 + + +@register_model("lstm_lm") +class LSTMLanguageModel(FairseqLanguageModel): + def __init__(self, decoder): + super().__init__(decoder) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--dropout', type=float, metavar='D', + help='dropout probability') + parser.add_argument('--decoder-embed-dim', type=int, metavar='N', + help='decoder embedding dimension') + parser.add_argument('--decoder-embed-path', type=str, metavar='STR', + help='path to pre-trained decoder embedding') + parser.add_argument('--decoder-hidden-size', type=int, metavar='N', + help='decoder hidden size') + parser.add_argument('--decoder-layers', type=int, metavar='N', + help='number of decoder layers') + parser.add_argument('--decoder-out-embed-dim', type=int, metavar='N', + help='decoder output embedding dimension') + parser.add_argument('--decoder-attention', type=str, metavar='BOOL', + help='decoder attention') + parser.add_argument('--adaptive-softmax-cutoff', metavar='EXPR', + help='comma separated list of adaptive softmax cutoff points. ' + 'Must be used with adaptive_loss criterion') + parser.add_argument('--residuals', default=False, + action='store_true', + help='applying residuals between LSTM layers') + + # Granular dropout settings (if not specified these default to --dropout) + parser.add_argument('--decoder-dropout-in', type=float, metavar='D', + help='dropout probability for decoder input embedding') + parser.add_argument('--decoder-dropout-out', type=float, metavar='D', + help='dropout probability for decoder output') + parser.add_argument('--share-decoder-input-output-embed', default=False, + action='store_true', + help='share decoder input and output embeddings') + # fmt: on + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present in older models + base_architecture(args) + + if getattr(args, "max_target_positions", None) is not None: + max_target_positions = args.max_target_positions + else: + max_target_positions = getattr( + args, "tokens_per_sample", DEFAULT_MAX_TARGET_POSITIONS + ) + + def load_pretrained_embedding_from_file(embed_path, dictionary, embed_dim): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + embed_tokens = Embedding(num_embeddings, embed_dim, padding_idx) + embed_dict = utils.parse_embedding(embed_path) + utils.print_embed_overlap(embed_dict, dictionary) + return utils.load_embedding(embed_dict, dictionary, embed_tokens) + + pretrained_decoder_embed = None + if args.decoder_embed_path: + pretrained_decoder_embed = load_pretrained_embedding_from_file( + args.decoder_embed_path, task.target_dictionary, args.decoder_embed_dim + ) + + if args.share_decoder_input_output_embed: + # double check all parameters combinations are valid + if task.source_dictionary != task.target_dictionary: + raise ValueError( + "--share-decoder-input-output-embeddings requires a joint dictionary" + ) + + if args.decoder_embed_dim != args.decoder_out_embed_dim: + raise ValueError( + "--share-decoder-input-output-embeddings requires " + "--decoder-embed-dim to match --decoder-out-embed-dim" + ) + + decoder = LSTMDecoder( + dictionary=task.dictionary, + embed_dim=args.decoder_embed_dim, + hidden_size=args.decoder_hidden_size, + out_embed_dim=args.decoder_out_embed_dim, + num_layers=args.decoder_layers, + dropout_in=args.decoder_dropout_in, + dropout_out=args.decoder_dropout_out, + attention=False, # decoder-only language model doesn't support attention + encoder_output_units=0, + pretrained_embed=pretrained_decoder_embed, + share_input_output_embed=args.share_decoder_input_output_embed, + adaptive_softmax_cutoff=( + utils.eval_str_list(args.adaptive_softmax_cutoff, type=int) + if args.criterion == "adaptive_loss" + else None + ), + max_target_positions=max_target_positions, + residuals=args.residuals, + ) + + return cls(decoder) + + +@register_model_architecture("lstm_lm", "lstm_lm") +def base_architecture(args): + args.dropout = getattr(args, "dropout", 0.1) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_hidden_size = getattr( + args, "decoder_hidden_size", args.decoder_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 1) + args.decoder_out_embed_dim = getattr(args, "decoder_out_embed_dim", 512) + args.decoder_attention = getattr(args, "decoder_attention", "0") + args.decoder_dropout_in = getattr(args, "decoder_dropout_in", args.dropout) + args.decoder_dropout_out = getattr(args, "decoder_dropout_out", args.dropout) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.adaptive_softmax_cutoff = getattr( + args, "adaptive_softmax_cutoff", "10000,50000,200000" + ) + args.residuals = getattr(args, "residuals", False) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/masked_lm.py b/PyTorch/NLP/new-Transformer/fairseq/models/masked_lm.py new file mode 100644 index 00000000..5cb49dd7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/masked_lm.py @@ -0,0 +1,404 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderModel, + register_model, + register_model_architecture, +) +from fairseq.modules import ( + LayerNorm, + SinusoidalPositionalEmbedding, + TransformerSentenceEncoder, +) +from fairseq.modules.transformer_sentence_encoder import init_bert_params +from fairseq.utils import safe_hasattr + + +logger = logging.getLogger(__name__) + + +@register_model("masked_lm") +class MaskedLMModel(FairseqEncoderModel): + """ + Class for training a Masked Language Model. It also supports an + additional sentence level prediction if the sent-loss argument is set. + """ + + def __init__(self, args, encoder): + super().__init__(encoder) + self.args = args + + # if specified then apply bert initialization on the model. We need + # to explictly call this to make sure that the output embeddings + # and projection layers are also correctly initialized + if getattr(args, "apply_bert_init", False): + self.apply(init_bert_params) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + # Arguments related to dropout + parser.add_argument( + "--dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--attention-dropout", + type=float, + metavar="D", + help="dropout probability for" " attention weights", + ) + parser.add_argument( + "--act-dropout", + type=float, + metavar="D", + help="dropout probability after" " activation in FFN", + ) + + # Arguments related to hidden states and self-attention + parser.add_argument( + "--encoder-ffn-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension for FFN", + ) + parser.add_argument( + "--encoder-layers", type=int, metavar="N", help="num encoder layers" + ) + parser.add_argument( + "--encoder-attention-heads", + type=int, + metavar="N", + help="num encoder attention heads", + ) + + # Arguments related to input and output embeddings + parser.add_argument( + "--encoder-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension", + ) + parser.add_argument( + "--share-encoder-input-output-embed", + action="store_true", + help="share encoder input" " and output embeddings", + ) + parser.add_argument( + "--encoder-learned-pos", + action="store_true", + help="use learned positional embeddings in the encoder", + ) + parser.add_argument( + "--no-token-positional-embeddings", + action="store_true", + help="if set, disables positional embeddings" " (outside self attention)", + ) + parser.add_argument( + "--num-segment", type=int, metavar="N", help="num segment in the input" + ) + parser.add_argument( + "--max-positions", type=int, help="number of positional embeddings to learn" + ) + + # Arguments related to sentence level prediction + parser.add_argument( + "--sentence-class-num", + type=int, + metavar="N", + help="number of classes for sentence task", + ) + parser.add_argument( + "--sent-loss", + action="store_true", + help="if set," " calculate sentence level predictions", + ) + + # Arguments related to parameter initialization + parser.add_argument( + "--apply-bert-init", + action="store_true", + help="use custom param initialization for BERT", + ) + + # misc params + parser.add_argument( + "--activation-fn", + choices=utils.get_available_activation_fns(), + help="activation function to use", + ) + parser.add_argument( + "--pooler-activation-fn", + choices=utils.get_available_activation_fns(), + help="Which activation function to use for pooler layer.", + ) + parser.add_argument( + "--encoder-normalize-before", + action="store_true", + help="apply layernorm before each encoder block", + ) + + def forward(self, src_tokens, segment_labels=None, **kwargs): + return self.encoder(src_tokens, segment_labels=segment_labels, **kwargs) + + def max_positions(self): + return self.encoder.max_positions + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + # make sure all arguments are present in older models + base_architecture(args) + + if not safe_hasattr(args, "max_positions"): + args.max_positions = args.tokens_per_sample + + logger.info(args) + + encoder = MaskedLMEncoder(args, task.dictionary) + return cls(args, encoder) + + +class MaskedLMEncoder(FairseqEncoder): + """ + Encoder for Masked Language Modelling. + """ + + def __init__(self, args, dictionary): + super().__init__(dictionary) + + self.padding_idx = dictionary.pad() + self.vocab_size = dictionary.__len__() + self.max_positions = args.max_positions + + self.sentence_encoder = TransformerSentenceEncoder( + padding_idx=self.padding_idx, + vocab_size=self.vocab_size, + num_encoder_layers=args.encoder_layers, + embedding_dim=args.encoder_embed_dim, + ffn_embedding_dim=args.encoder_ffn_embed_dim, + num_attention_heads=args.encoder_attention_heads, + dropout=args.dropout, + attention_dropout=args.attention_dropout, + activation_dropout=args.act_dropout, + max_seq_len=self.max_positions, + num_segments=args.num_segment, + use_position_embeddings=not args.no_token_positional_embeddings, + encoder_normalize_before=args.encoder_normalize_before, + apply_bert_init=args.apply_bert_init, + activation_fn=args.activation_fn, + learned_pos_embedding=args.encoder_learned_pos, + ) + + self.share_input_output_embed = args.share_encoder_input_output_embed + self.embed_out = None + self.sentence_projection_layer = None + self.sentence_out_dim = args.sentence_class_num + self.lm_output_learned_bias = None + + # Remove head is set to true during fine-tuning + self.load_softmax = not getattr(args, "remove_head", False) + + self.masked_lm_pooler = nn.Linear( + args.encoder_embed_dim, args.encoder_embed_dim + ) + self.pooler_activation = utils.get_activation_fn(args.pooler_activation_fn) + + self.lm_head_transform_weight = nn.Linear( + args.encoder_embed_dim, args.encoder_embed_dim + ) + self.activation_fn = utils.get_activation_fn(args.activation_fn) + self.layer_norm = LayerNorm(args.encoder_embed_dim) + + self.lm_output_learned_bias = None + if self.load_softmax: + self.lm_output_learned_bias = nn.Parameter(torch.zeros(self.vocab_size)) + + if not self.share_input_output_embed: + self.embed_out = nn.Linear( + args.encoder_embed_dim, self.vocab_size, bias=False + ) + + if args.sent_loss: + self.sentence_projection_layer = nn.Linear( + args.encoder_embed_dim, self.sentence_out_dim, bias=False + ) + + def forward(self, src_tokens, segment_labels=None, masked_tokens=None, **unused): + """ + Forward pass for Masked LM encoder. This first computes the token + embedding using the token embedding matrix, position embeddings (if + specified) and segment embeddings (if specified). + + Here we assume that the sentence representation corresponds to the + output of the classification_token (see bert_task or cross_lingual_lm + task for more details). + Args: + - src_tokens: B x T matrix representing sentences + - segment_labels: B x T matrix representing segment label for tokens + Returns: + - a tuple of the following: + - logits for predictions in format B x T x C to be used in + softmax afterwards + - a dictionary of additional data, where 'pooled_output' contains + the representation for classification_token and 'inner_states' + is a list of internal model states used to compute the + predictions (similar in ELMO). 'sentence_logits' + is the prediction logit for NSP task and is only computed if + this is specified in the input arguments. + """ + + inner_states, sentence_rep = self.sentence_encoder( + src_tokens, + segment_labels=segment_labels, + ) + + x = inner_states[-1].transpose(0, 1) + # project masked tokens only + if masked_tokens is not None: + x = x[masked_tokens, :] + x = self.layer_norm(self.activation_fn(self.lm_head_transform_weight(x))) + + pooled_output = self.pooler_activation(self.masked_lm_pooler(sentence_rep)) + + # project back to size of vocabulary + if self.share_input_output_embed and hasattr( + self.sentence_encoder.embed_tokens, "weight" + ): + x = F.linear(x, self.sentence_encoder.embed_tokens.weight) + elif self.embed_out is not None: + x = self.embed_out(x) + if self.lm_output_learned_bias is not None: + x = x + self.lm_output_learned_bias + sentence_logits = None + if self.sentence_projection_layer: + sentence_logits = self.sentence_projection_layer(pooled_output) + + return x, { + "inner_states": inner_states, + "pooled_output": pooled_output, + "sentence_logits": sentence_logits, + } + + def max_positions(self): + """Maximum output length supported by the encoder.""" + return self.max_positions + + def upgrade_state_dict_named(self, state_dict, name): + if isinstance( + self.sentence_encoder.embed_positions, SinusoidalPositionalEmbedding + ): + state_dict[ + name + ".sentence_encoder.embed_positions._float_tensor" + ] = torch.FloatTensor(1) + if not self.load_softmax: + for k in list(state_dict.keys()): + if ( + "embed_out.weight" in k + or "sentence_projection_layer.weight" in k + or "lm_output_learned_bias" in k + ): + del state_dict[k] + return state_dict + + +@register_model_architecture("masked_lm", "masked_lm") +def base_architecture(args): + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.act_dropout = getattr(args, "act_dropout", 0.0) + + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4096) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.share_encoder_input_output_embed = getattr( + args, "share_encoder_input_output_embed", False + ) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", False) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.num_segment = getattr(args, "num_segment", 2) + + args.sentence_class_num = getattr(args, "sentence_class_num", 2) + args.sent_loss = getattr(args, "sent_loss", False) + + args.apply_bert_init = getattr(args, "apply_bert_init", False) + + args.activation_fn = getattr(args, "activation_fn", "relu") + args.pooler_activation_fn = getattr(args, "pooler_activation_fn", "tanh") + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + + +@register_model_architecture("masked_lm", "bert_base") +def bert_base_architecture(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 768) + args.share_encoder_input_output_embed = getattr( + args, "share_encoder_input_output_embed", True + ) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", True) + args.num_segment = getattr(args, "num_segment", 2) + + args.encoder_layers = getattr(args, "encoder_layers", 12) + + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 12) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 3072) + + args.sentence_class_num = getattr(args, "sentence_class_num", 2) + args.sent_loss = getattr(args, "sent_loss", True) + + args.apply_bert_init = getattr(args, "apply_bert_init", True) + + args.activation_fn = getattr(args, "activation_fn", "gelu") + args.pooler_activation_fn = getattr(args, "pooler_activation_fn", "tanh") + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", True) + base_architecture(args) + + +@register_model_architecture("masked_lm", "bert_large") +def bert_large_architecture(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.encoder_layers = getattr(args, "encoder_layers", 24) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 16) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4096) + bert_base_architecture(args) + + +@register_model_architecture("masked_lm", "xlm_base") +def xlm_architecture(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.share_encoder_input_output_embed = getattr( + args, "share_encoder_input_output_embed", True + ) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", True) + args.num_segment = getattr(args, "num_segment", 1) + + args.encoder_layers = getattr(args, "encoder_layers", 6) + + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4096) + + args.sent_loss = getattr(args, "sent_loss", False) + + args.activation_fn = getattr(args, "activation_fn", "gelu") + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.pooler_activation_fn = getattr(args, "pooler_activation_fn", "tanh") + args.apply_bert_init = getattr(args, "apply_bert_init", True) + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/model_utils.py b/PyTorch/NLP/new-Transformer/fairseq/models/model_utils.py new file mode 100644 index 00000000..732d66b1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/model_utils.py @@ -0,0 +1,92 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import List, Optional + +import torch +from torch import Tensor + + +@torch.jit.script +def script_skip_tensor_list(x: List[Tensor], mask): + res = [xi[mask] if xi.size(0) == mask.size(0) else xi[:, mask] for xi in x] + outputs = [] + for i, t in enumerate(res): + if t.numel() != 0: + outputs.append(t) + else: + outputs.append(x[i]) + return outputs + + +@torch.jit.script +def script_skip_tensor(x: Tensor, mask): + # None case + if x.size(0) == 0: + return x + res = x[mask] if x.size(0) == mask.size(0) else x[:, mask] + if res.numel() == 0: + return x + else: + return res + + +@torch.jit.script +def expand_2d_or_3d_tensor(x, trg_dim: int, padding_idx: int): + """ + Expand 2D/3D tensor on dim=1 + """ + if x is None: + return None + + assert x.dim() == 2 or x.dim() == 3 + assert trg_dim >= x.size(1), (trg_dim, x.size()) + if trg_dim == x.size(1): + return x + + dims = [x.size(0), trg_dim - x.size(1)] + if x.dim() == 3: + dims.append(x.size(2)) + x = torch.cat([x, torch.zeros(dims).to(x).fill_(padding_idx)], 1) + + return x + + +@torch.jit.script +def coalesce(x: Optional[Tensor], y: Tensor) -> Tensor: + return x if x is not None else y + + +@torch.jit.script +def fill_tensors( + x: Optional[Tensor], mask, y: Optional[Tensor], padding_idx: int +) -> Optional[Tensor]: + """ + Filling tensor x with y at masked positions (dim=0). + """ + if x is None or x.size()[0] == 0 or y is None: + return x + assert x.dim() == y.dim() and mask.size(0) == x.size(0) + assert x.dim() == 2 or (x.dim() == 3 and x.size(2) == y.size(2)) + + n_selected = mask.sum() + if n_selected == 0: + return x + assert n_selected == y.size(0) + if n_selected == x.size(0): + return y + + if x.size(1) < y.size(1): + x = expand_2d_or_3d_tensor(x, y.size(1), padding_idx) + x[mask] = y + elif x.size(1) > y.size(1): + x[mask] = torch.tensor(padding_idx).type_as(x) + if x.dim() == 2: + x[mask, : y.size(1)] = y + else: + x[mask, : y.size(1), :] = y + else: + x[mask] = y + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/multilingual_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/multilingual_transformer.py new file mode 100644 index 00000000..e722b647 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/multilingual_transformer.py @@ -0,0 +1,229 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections import OrderedDict + +from fairseq import utils +from fairseq.models import ( + FairseqMultiModel, + register_model, + register_model_architecture, +) +from fairseq.models.transformer import ( + Embedding, + TransformerDecoder, + TransformerEncoder, + TransformerModel, + base_architecture, +) +from fairseq.utils import safe_hasattr + + +@register_model("multilingual_transformer") +class MultilingualTransformerModel(FairseqMultiModel): + """Train Transformer models for multiple language pairs simultaneously. + + Requires `--task multilingual_translation`. + + We inherit all arguments from TransformerModel and assume that all language + pairs use a single Transformer architecture. In addition, we provide several + options that are specific to the multilingual setting. + + Args: + --share-encoder-embeddings: share encoder embeddings across all source languages + --share-decoder-embeddings: share decoder embeddings across all target languages + --share-encoders: share all encoder params (incl. embeddings) across all source languages + --share-decoders: share all decoder params (incl. embeddings) across all target languages + """ + + def __init__(self, encoders, decoders): + super().__init__(encoders, decoders) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + TransformerModel.add_args(parser) + parser.add_argument( + "--share-encoder-embeddings", + action="store_true", + help="share encoder embeddings across languages", + ) + parser.add_argument( + "--share-decoder-embeddings", + action="store_true", + help="share decoder embeddings across languages", + ) + parser.add_argument( + "--share-encoders", + action="store_true", + help="share encoders across languages", + ) + parser.add_argument( + "--share-decoders", + action="store_true", + help="share decoders across languages", + ) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + from fairseq.tasks.multilingual_translation import MultilingualTranslationTask + + assert isinstance(task, MultilingualTranslationTask) + + # make sure all arguments are present in older models + base_multilingual_architecture(args) + + if not safe_hasattr(args, "max_source_positions"): + args.max_source_positions = 1024 + if not safe_hasattr(args, "max_target_positions"): + args.max_target_positions = 1024 + + src_langs = [lang_pair.split("-")[0] for lang_pair in task.model_lang_pairs] + tgt_langs = [lang_pair.split("-")[1] for lang_pair in task.model_lang_pairs] + + if args.share_encoders: + args.share_encoder_embeddings = True + if args.share_decoders: + args.share_decoder_embeddings = True + + def build_embedding(dictionary, embed_dim, path=None): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + emb = Embedding(num_embeddings, embed_dim, padding_idx) + # if provided, load from preloaded dictionaries + if path: + embed_dict = utils.parse_embedding(path) + utils.load_embedding(embed_dict, dictionary, emb) + return emb + + # build shared embeddings (if applicable) + shared_encoder_embed_tokens, shared_decoder_embed_tokens = None, None + if args.share_all_embeddings: + if args.encoder_embed_dim != args.decoder_embed_dim: + raise ValueError( + "--share-all-embeddings requires --encoder-embed-dim to match --decoder-embed-dim" + ) + if args.decoder_embed_path and ( + args.decoder_embed_path != args.encoder_embed_path + ): + raise ValueError( + "--share-all-embeddings not compatible with --decoder-embed-path" + ) + shared_encoder_embed_tokens = FairseqMultiModel.build_shared_embeddings( + dicts=task.dicts, + langs=task.langs, + embed_dim=args.encoder_embed_dim, + build_embedding=build_embedding, + pretrained_embed_path=args.encoder_embed_path, + ) + shared_decoder_embed_tokens = shared_encoder_embed_tokens + args.share_decoder_input_output_embed = True + else: + if args.share_encoder_embeddings: + shared_encoder_embed_tokens = FairseqMultiModel.build_shared_embeddings( + dicts=task.dicts, + langs=src_langs, + embed_dim=args.encoder_embed_dim, + build_embedding=build_embedding, + pretrained_embed_path=args.encoder_embed_path, + ) + if args.share_decoder_embeddings: + shared_decoder_embed_tokens = FairseqMultiModel.build_shared_embeddings( + dicts=task.dicts, + langs=tgt_langs, + embed_dim=args.decoder_embed_dim, + build_embedding=build_embedding, + pretrained_embed_path=args.decoder_embed_path, + ) + + # encoders/decoders for each language + lang_encoders, lang_decoders = {}, {} + + def get_encoder(lang): + if lang not in lang_encoders: + if shared_encoder_embed_tokens is not None: + encoder_embed_tokens = shared_encoder_embed_tokens + else: + encoder_embed_tokens = build_embedding( + task.dicts[lang], + args.encoder_embed_dim, + args.encoder_embed_path, + ) + lang_encoders[lang] = cls._get_module_class( + True, args, task.dicts[lang], encoder_embed_tokens, src_langs + ) + return lang_encoders[lang] + + def get_decoder(lang): + if lang not in lang_decoders: + if shared_decoder_embed_tokens is not None: + decoder_embed_tokens = shared_decoder_embed_tokens + else: + decoder_embed_tokens = build_embedding( + task.dicts[lang], + args.decoder_embed_dim, + args.decoder_embed_path, + ) + lang_decoders[lang] = cls._get_module_class( + False, args, task.dicts[lang], decoder_embed_tokens, tgt_langs + ) + return lang_decoders[lang] + + # shared encoders/decoders (if applicable) + shared_encoder, shared_decoder = None, None + if args.share_encoders: + shared_encoder = get_encoder(src_langs[0]) + if args.share_decoders: + shared_decoder = get_decoder(tgt_langs[0]) + + encoders, decoders = OrderedDict(), OrderedDict() + for lang_pair, src, tgt in zip(task.model_lang_pairs, src_langs, tgt_langs): + encoders[lang_pair] = ( + shared_encoder if shared_encoder is not None else get_encoder(src) + ) + decoders[lang_pair] = ( + shared_decoder if shared_decoder is not None else get_decoder(tgt) + ) + + return MultilingualTransformerModel(encoders, decoders) + + @classmethod + def _get_module_class(cls, is_encoder, args, lang_dict, embed_tokens, langs): + module_class = TransformerEncoder if is_encoder else TransformerDecoder + return module_class(args, lang_dict, embed_tokens) + + def load_state_dict(self, state_dict, strict=True, model_cfg=None): + state_dict_subset = state_dict.copy() + for k, _ in state_dict.items(): + assert k.startswith("models.") + lang_pair = k.split(".")[1] + if lang_pair not in self.models: + del state_dict_subset[k] + super().load_state_dict(state_dict_subset, strict=strict, model_cfg=model_cfg) + + +@register_model_architecture("multilingual_transformer", "multilingual_transformer") +def base_multilingual_architecture(args): + base_architecture(args) + args.share_encoder_embeddings = getattr(args, "share_encoder_embeddings", False) + args.share_decoder_embeddings = getattr(args, "share_decoder_embeddings", False) + args.share_encoders = getattr(args, "share_encoders", False) + args.share_decoders = getattr(args, "share_decoders", False) + + +@register_model_architecture( + "multilingual_transformer", "multilingual_transformer_iwslt_de_en" +) +def multilingual_transformer_iwslt_de_en(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 1024) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 1024) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 4) + args.decoder_layers = getattr(args, "decoder_layers", 6) + base_multilingual_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/__init__.py new file mode 100644 index 00000000..05fe8224 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/__init__.py @@ -0,0 +1,13 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +from .fairseq_nat_model import * +from .nonautoregressive_transformer import * +from .nat_crf_transformer import * +from .iterative_nonautoregressive_transformer import * +from .cmlm_transformer import * +from .levenshtein_transformer import * +from .insertion_transformer import * diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/cmlm_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/cmlm_transformer.py new file mode 100644 index 00000000..c876e945 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/cmlm_transformer.py @@ -0,0 +1,162 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +""" +This file implements: +Ghazvininejad, Marjan, et al. +"Constant-time machine translation with conditional masked language models." +arXiv preprint arXiv:1904.09324 (2019). +""" + +from fairseq.models import register_model, register_model_architecture +from fairseq.models.nat import NATransformerModel +from fairseq.utils import new_arange + + +def _skeptical_unmasking(output_scores, output_masks, p): + sorted_index = output_scores.sort(-1)[1] + boundary_len = ( + (output_masks.sum(1, keepdim=True).type_as(output_scores) - 2) * p + ).long() + skeptical_mask = new_arange(output_masks) < boundary_len + return skeptical_mask.scatter(1, sorted_index, skeptical_mask) + + +@register_model("cmlm_transformer") +class CMLMNATransformerModel(NATransformerModel): + @staticmethod + def add_args(parser): + NATransformerModel.add_args(parser) + + def forward( + self, src_tokens, src_lengths, prev_output_tokens, tgt_tokens, **kwargs + ): + assert not self.decoder.src_embedding_copy, "do not support embedding copy." + + # encoding + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + # length prediction + length_out = self.decoder.forward_length( + normalize=False, encoder_out=encoder_out + ) + length_tgt = self.decoder.forward_length_prediction( + length_out, encoder_out, tgt_tokens + ) + + # decoding + word_ins_out = self.decoder( + normalize=False, + prev_output_tokens=prev_output_tokens, + encoder_out=encoder_out, + ) + word_ins_mask = prev_output_tokens.eq(self.unk) + + return { + "word_ins": { + "out": word_ins_out, + "tgt": tgt_tokens, + "mask": word_ins_mask, + "ls": self.args.label_smoothing, + "nll_loss": True, + }, + "length": { + "out": length_out, + "tgt": length_tgt, + "factor": self.decoder.length_loss_factor, + }, + } + + def forward_decoder(self, decoder_out, encoder_out, decoding_format=None, **kwargs): + + step = decoder_out.step + max_step = decoder_out.max_step + + output_tokens = decoder_out.output_tokens + output_scores = decoder_out.output_scores + history = decoder_out.history + + # execute the decoder + output_masks = output_tokens.eq(self.unk) + _scores, _tokens = self.decoder( + normalize=True, + prev_output_tokens=output_tokens, + encoder_out=encoder_out, + ).max(-1) + output_tokens.masked_scatter_(output_masks, _tokens[output_masks]) + output_scores.masked_scatter_(output_masks, _scores[output_masks]) + + if history is not None: + history.append(output_tokens.clone()) + + # skeptical decoding (depend on the maximum decoding steps.) + if (step + 1) < max_step: + skeptical_mask = _skeptical_unmasking( + output_scores, output_tokens.ne(self.pad), 1 - (step + 1) / max_step + ) + + output_tokens.masked_fill_(skeptical_mask, self.unk) + output_scores.masked_fill_(skeptical_mask, 0.0) + + if history is not None: + history.append(output_tokens.clone()) + + return decoder_out._replace( + output_tokens=output_tokens, + output_scores=output_scores, + attn=None, + history=history, + ) + + +@register_model_architecture("cmlm_transformer", "cmlm_transformer") +def cmlm_base_architecture(args): + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", False) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.dropout = getattr(args, "dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", True) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.apply_bert_init = getattr(args, "apply_bert_init", False) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + # --- special arguments --- + args.sg_length_pred = getattr(args, "sg_length_pred", False) + args.pred_length_offset = getattr(args, "pred_length_offset", False) + args.length_loss_factor = getattr(args, "length_loss_factor", 0.1) + args.ngram_predictor = getattr(args, "ngram_predictor", 1) + args.src_embedding_copy = getattr(args, "src_embedding_copy", False) + + +@register_model_architecture("cmlm_transformer", "cmlm_transformer_wmt_en_de") +def cmlm_wmt_en_de(args): + cmlm_base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/fairseq_nat_model.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/fairseq_nat_model.py new file mode 100644 index 00000000..a5594a4e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/fairseq_nat_model.py @@ -0,0 +1,172 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch +from fairseq.models.transformer import ( + TransformerDecoder, + TransformerEncoder, + TransformerModel, +) +from fairseq.modules.transformer_sentence_encoder import init_bert_params + + +def ensemble_encoder(func): + def wrapper(self, *args, **kwargs): + if self.ensemble_models is None or len(self.ensemble_models) == 1: + return func(self, *args, **kwargs) + encoder_outs = [ + func(model, *args, **kwargs, return_all_hiddens=True) + for model in self.ensemble_models + ] + _encoder_out = encoder_outs[0].copy() + + def stack(key): + outs = [e[key][0] for e in encoder_outs] + return [torch.stack(outs, -1) if outs[0] is not None else None] + + _encoder_out["encoder_out"] = stack("encoder_out") + _encoder_out["encoder_embedding"] = stack("encoder_embedding") + + num_layers = len(_encoder_out["encoder_states"]) + if num_layers > 0: + _encoder_out["encoder_states"] = [ + torch.stack([e["encoder_states"][i] for e in encoder_outs], -1) + for i in range(num_layers) + ] + return _encoder_out + + return wrapper + + +def ensemble_decoder(func): + def wrapper(self, normalize=False, encoder_out=None, *args, **kwargs): + if self.ensemble_models is None or len(self.ensemble_models) == 1: + return func( + self, normalize=normalize, encoder_out=encoder_out, *args, **kwargs + ) + + def _replace(encoder_out, new_val): + new_encoder_out = encoder_out.copy() + new_encoder_out["encoder_out"] = [new_val] + return new_encoder_out + + action_outs = [ + func( + model, + normalize=normalize, + encoder_out=_replace( + encoder_out, encoder_out["encoder_out"][0][:, :, :, i] + ), + *args, + **kwargs + ) + for i, model in enumerate(self.ensemble_models) + ] + + if not isinstance(action_outs[0], tuple): # return multiple values + action_outs = [[a] for a in action_outs] + else: + action_outs = [list(a) for a in action_outs] + + ensembled_outs = [] + for i in range(len(action_outs[0])): + if i == 0 and normalize: + ensembled_outs += [ + torch.logsumexp( + torch.stack([a[i] for a in action_outs], -1), dim=-1 + ) + - math.log(len(self.ensemble_models)) + ] + elif action_outs[0][i] is not None: + ensembled_outs += [torch.stack([a[i] for a in action_outs], -1)] + else: + ensembled_outs += [None] + + if len(ensembled_outs) == 1: + return ensembled_outs[0] + return tuple(ensembled_outs) + + return wrapper + + +class FairseqNATModel(TransformerModel): + """ + Abstract class for all nonautoregressive-based models + """ + + def __init__(self, args, encoder, decoder): + super().__init__(args, encoder, decoder) + self.tgt_dict = decoder.dictionary + self.bos = decoder.dictionary.bos() + self.eos = decoder.dictionary.eos() + self.pad = decoder.dictionary.pad() + self.unk = decoder.dictionary.unk() + + self.ensemble_models = None + + @property + def allow_length_beam(self): + return False + + @property + def allow_ensemble(self): + return True + + def enable_ensemble(self, models): + self.encoder.ensemble_models = [m.encoder for m in models] + self.decoder.ensemble_models = [m.decoder for m in models] + + @staticmethod + def add_args(parser): + TransformerModel.add_args(parser) + parser.add_argument( + "--apply-bert-init", + action="store_true", + help="use custom param initialization for BERT", + ) + + @classmethod + def build_decoder(cls, args, tgt_dict, embed_tokens): + decoder = FairseqNATDecoder(args, tgt_dict, embed_tokens) + if getattr(args, "apply_bert_init", False): + decoder.apply(init_bert_params) + return decoder + + @classmethod + def build_encoder(cls, args, src_dict, embed_tokens): + encoder = FairseqNATEncoder(args, src_dict, embed_tokens) + if getattr(args, "apply_bert_init", False): + encoder.apply(init_bert_params) + return encoder + + def forward_encoder(self, encoder_inputs): + return self.encoder(*encoder_inputs) + + def forward_decoder(self, *args, **kwargs): + return NotImplementedError + + def initialize_output_tokens(self, *args, **kwargs): + return NotImplementedError + + def forward(self, *args, **kwargs): + return NotImplementedError + + +class FairseqNATEncoder(TransformerEncoder): + def __init__(self, args, dictionary, embed_tokens): + super().__init__(args, dictionary, embed_tokens) + self.ensemble_models = None + + @ensemble_encoder + def forward(self, *args, **kwargs): + return super().forward(*args, **kwargs) + + +class FairseqNATDecoder(TransformerDecoder): + def __init__(self, args, dictionary, embed_tokens, no_encoder_attn=False): + super().__init__(args, dictionary, embed_tokens, no_encoder_attn) + self.ensemble_models = None diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/insertion_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/insertion_transformer.py new file mode 100644 index 00000000..bc28000f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/insertion_transformer.py @@ -0,0 +1,280 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch +import torch.nn.functional as F +from fairseq.models import register_model, register_model_architecture +from fairseq.models.nat import ( + FairseqNATModel, + LevenshteinTransformerDecoder, + LevenshteinTransformerModel, + ensemble_decoder, +) +from fairseq.models.transformer import Linear +from fairseq.modules.transformer_sentence_encoder import init_bert_params +from fairseq.utils import new_arange + + +class NegativeDistanceScore(object): + def __init__(self): + + # pre-compute some values + self.scores = {} + + self.scores[0.5] = self.compute_score_full(50, 0.5) + self.scores[1.0] = self.compute_score_full(50, 1.0) + self.scores[2.0] = self.compute_score_full(50, 2.0) + + def __call__(self, i, L, tau): + if (tau is None) or (tau > 1000): + return 1 / L + + if tau in self.scores: + if L < self.scores[tau].shape[0]: + return self.scores[tau][L - 1, i] + return self.compute_score(L, tau)[i] + + def compute_score(self, L, tau): + s = np.array([-abs(L / 2 - i) / tau for i in range(L)]) + s = np.exp(s - s.max()) + return s / s.sum() + + def compute_score_full(self, L, tau): + s = -abs(np.arange(0, L - 1)[:, None] / 2 - np.arange(L)[None, :]) / tau + s = np.tril(s, 0) + np.triu(s - float("inf"), 1) + s = np.exp(s - s.max(1, keepdims=True)) + return s / s.sum(1, keepdims=True) + + +neg_scorer = NegativeDistanceScore() + + +def _get_ins_targets(in_tokens, out_tokens, padding_idx, unk_idx, vocab_size, tau=None): + try: + from fairseq import libnat + except ImportError as e: + import sys + + sys.stderr.write("ERROR: missing libnat. run `pip install --editable .`\n") + raise e + + B = in_tokens.size(0) + T = in_tokens.size(1) + V = vocab_size + + with torch.cuda.device_of(in_tokens): + in_tokens_list = [ + [t for t in s if t != padding_idx] for i, s in enumerate(in_tokens.tolist()) + ] + out_tokens_list = [ + [t for t in s if t != padding_idx] + for i, s in enumerate(out_tokens.tolist()) + ] + + full_labels = libnat.suggested_ed2_path( + in_tokens_list, out_tokens_list, padding_idx + ) + insert_labels = [a[:-1] for a in full_labels] + + # numericalize1 + insert_label_tensors = in_tokens.new_zeros(B * (T - 1) * V).float() + insert_index, insert_labels = zip( + *[ + (w + (j + i * (T - 1)) * V, neg_scorer(k, len(label), tau)) + for i, labels in enumerate(insert_labels) + for j, label in enumerate(labels[1:-1]) + for k, w in enumerate(label) + ] + ) # HACK 1:-1 + insert_index, insert_labels = [ + torch.tensor(list(a), device=in_tokens.device) + for a in [insert_index, insert_labels] + ] + insert_label_tensors.scatter_(0, insert_index.long(), insert_labels) + insert_label_tensors = insert_label_tensors.view(B, T - 1, V) + + return insert_label_tensors + + +def _apply_ins_words(in_tokens, in_scores, word_ins_pred, word_ins_scores, padding_idx): + + padding_masks = in_tokens[:, 1:].eq(padding_idx) + word_ins_scores.masked_fill_(padding_masks, 0.0) + word_ins_pred.masked_fill_(padding_masks, padding_idx) + + in_coords = new_arange(in_tokens).type_as(in_scores) + + # shift all padding predictions to infinite + out_coords = (in_coords[:, 1:] - 0.5).masked_fill( + word_ins_pred.eq(padding_idx), float("inf") + ) + out_coords = torch.cat([in_coords, out_coords], 1).sort(-1)[1] + out_tokens = torch.cat([in_tokens, word_ins_pred], 1).gather(1, out_coords) + out_scores = torch.cat([in_scores, word_ins_scores], 1).gather(1, out_coords) + return out_tokens, out_scores + + +@register_model("insertion_transformer") +class InsertionTransformerModel(LevenshteinTransformerModel): + def __init__(self, args, encoder, decoder): + super().__init__(args, encoder, decoder) + + @staticmethod + def add_args(parser): + FairseqNATModel.add_args(parser) + parser.add_argument("--label-tau", default=None, type=float) + + @classmethod + def build_decoder(cls, args, tgt_dict, embed_tokens): + decoder = InsertionTransformerDecoder(args, tgt_dict, embed_tokens) + if getattr(args, "apply_bert_init", False): + decoder.apply(init_bert_params) + return decoder + + def forward( + self, src_tokens, src_lengths, prev_output_tokens, tgt_tokens, **kwargs + ): + + assert tgt_tokens is not None, "forward function only supports training." + + # encoding + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + + # generate training labels for insertion + word_ins_out = self.decoder.forward_word_ins( + normalize=False, + prev_output_tokens=prev_output_tokens, + encoder_out=encoder_out, + ) + + word_ins_tgt = _get_ins_targets( + prev_output_tokens, + tgt_tokens, + self.pad, + self.unk, + len(self.tgt_dict), + tau=self.decoder.label_tau, + ).type_as(word_ins_out) + word_ins_masks = prev_output_tokens[:, 1:].ne(self.pad) + + return { + "word_ins": { + "out": word_ins_out, + "tgt": word_ins_tgt, + "mask": word_ins_masks, + "ls": self.args.label_smoothing, + "nll_loss": True, + } + } + + def forward_decoder( + self, decoder_out, encoder_out, eos_penalty=0.0, max_ratio=None, **kwargs + ): + + output_tokens = decoder_out.output_tokens + output_scores = decoder_out.output_scores + history = decoder_out.history + + # TODO: decoding for InsertionTransformer + word_ins_score = self.decoder.forward_word_ins( + normalize=True, prev_output_tokens=output_tokens, encoder_out=encoder_out + ) + + if eos_penalty > 0.0: + word_ins_score[:, :, self.pad] -= eos_penalty + word_ins_score, word_ins_pred = word_ins_score.max(-1) + output_tokens, output_scores = _apply_ins_words( + output_tokens, output_scores, word_ins_pred, word_ins_score, self.pad + ) + + # delete some unnecessary paddings + cut_off = output_tokens.ne(self.pad).sum(1).max() + output_tokens = output_tokens[:, :cut_off] + output_scores = output_scores[:, :cut_off] + + if history is not None: + history.append(output_tokens.clone()) + + return decoder_out._replace( + output_tokens=output_tokens, + output_scores=output_scores, + attn=None, + history=history, + ) + + +class InsertionTransformerDecoder(LevenshteinTransformerDecoder): + def __init__(self, args, dictionary, embed_tokens, no_encoder_attn=False): + # use the TransformerDecoder's __init__ + super(LevenshteinTransformerDecoder, self).__init__( + args, dictionary, embed_tokens, no_encoder_attn=no_encoder_attn + ) + + self.dictionary = dictionary + self.bos = dictionary.bos() + self.unk = dictionary.unk() + self.eos = dictionary.eos() + self.pool_out = Linear(self.output_embed_dim * 2, self.output_embed_dim) + + self.label_tau = getattr(args, "label_tau", None) + + @ensemble_decoder + def forward_word_ins(self, normalize, encoder_out, prev_output_tokens): + features = self.extract_features(prev_output_tokens, encoder_out=encoder_out)[0] + features = self.pool_out( + torch.cat([features[:, :-1, :], features[:, 1:, :]], 2) + ) + decoder_out = self.output_layer(features) + return F.log_softmax(decoder_out, -1) if normalize else decoder_out + + def forward_mask_ins(self, *args, **kwargs): + raise NotImplementedError + + def forward_word_del(self, *args, **kwargs): + raise NotImplementedError + + +@register_model_architecture("insertion_transformer", "insertion_transformer") +def insertion_base_architecture(args): + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", False) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.dropout = getattr(args, "dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", False) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.apply_bert_init = getattr(args, "apply_bert_init", False) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + # special for insertion transformer + args.label_tau = getattr(args, "label_tau", None) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/iterative_nonautoregressive_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/iterative_nonautoregressive_transformer.py new file mode 100644 index 00000000..bc395099 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/iterative_nonautoregressive_transformer.py @@ -0,0 +1,228 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from fairseq.models import register_model, register_model_architecture +from fairseq.models.nat import NATransformerModel + + +def _sequential_poisoning(s, V, beta=0.33, bos=2, eos=3, pad=1): + # s: input batch + # V: vocabulary size + rand_words = torch.randint(low=4, high=V, size=s.size(), device=s.device) + choices = torch.rand(size=s.size(), device=s.device) + choices.masked_fill_((s == pad) | (s == bos) | (s == eos), 1) + + replace = choices < beta / 3 + repeat = (choices >= beta / 3) & (choices < beta * 2 / 3) + swap = (choices >= beta * 2 / 3) & (choices < beta) + safe = choices >= beta + + for i in range(s.size(1) - 1): + rand_word = rand_words[:, i] + next_word = s[:, i + 1] + self_word = s[:, i] + + replace_i = replace[:, i] + swap_i = swap[:, i] & (next_word != 3) + repeat_i = repeat[:, i] & (next_word != 3) + safe_i = safe[:, i] | ((next_word == 3) & (~replace_i)) + + s[:, i] = ( + self_word * (safe_i | repeat_i).long() + + next_word * swap_i.long() + + rand_word * replace_i.long() + ) + s[:, i + 1] = ( + next_word * (safe_i | replace_i).long() + + self_word * (swap_i | repeat_i).long() + ) + return s + + +def gumbel_noise(input, TINY=1e-8): + return ( + input.new_zeros(*input.size()) + .uniform_() + .add_(TINY) + .log_() + .neg_() + .add_(TINY) + .log_() + .neg_() + ) + + +@register_model("iterative_nonautoregressive_transformer") +class IterNATransformerModel(NATransformerModel): + @staticmethod + def add_args(parser): + NATransformerModel.add_args(parser) + parser.add_argument( + "--train-step", + type=int, + help="number of refinement iterations during training", + ) + parser.add_argument( + "--dae-ratio", + type=float, + help="the probability of switching to the denoising auto-encoder loss", + ) + parser.add_argument( + "--stochastic-approx", + action="store_true", + help="sampling from the decoder as the inputs for next iteration", + ) + + @classmethod + def build_model(cls, args, task): + model = super().build_model(args, task) + model.train_step = getattr(args, "train_step", 4) + model.dae_ratio = getattr(args, "dae_ratio", 0.5) + model.stochastic_approx = getattr(args, "stochastic_approx", False) + return model + + def forward( + self, src_tokens, src_lengths, prev_output_tokens, tgt_tokens, **kwargs + ): + + B, T = prev_output_tokens.size() + + # encoding + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + + # length prediction + length_out = self.decoder.forward_length( + normalize=False, encoder_out=encoder_out + ) + length_tgt = self.decoder.forward_length_prediction( + length_out, encoder_out, tgt_tokens + ) + + # decoding + word_ins_outs, word_ins_tgts, word_ins_masks = [], [], [] + for t in range(self.train_step): + word_ins_out = self.decoder( + normalize=False, + prev_output_tokens=prev_output_tokens, + encoder_out=encoder_out, + step=t, + ) + word_ins_tgt = tgt_tokens + word_ins_mask = word_ins_tgt.ne(self.pad) + + word_ins_outs.append(word_ins_out) + word_ins_tgts.append(word_ins_tgt) + word_ins_masks.append(word_ins_mask) + + if t < (self.train_step - 1): + # prediction for next iteration + if self.stochastic_approx: + word_ins_prediction = ( + word_ins_out + gumbel_noise(word_ins_out) + ).max(-1)[1] + else: + word_ins_prediction = word_ins_out.max(-1)[1] + + prev_output_tokens = prev_output_tokens.masked_scatter( + word_ins_mask, word_ins_prediction[word_ins_mask] + ) + + if self.dae_ratio > 0: + # we do not perform denoising for the first iteration + corrputed = ( + torch.rand(size=(B,), device=prev_output_tokens.device) + < self.dae_ratio + ) + corrputed_tokens = _sequential_poisoning( + tgt_tokens[corrputed], + len(self.tgt_dict), + 0.33, + self.bos, + self.eos, + self.pad, + ) + prev_output_tokens[corrputed] = corrputed_tokens + + # concat everything + word_ins_out = torch.cat(word_ins_outs, 0) + word_ins_tgt = torch.cat(word_ins_tgts, 0) + word_ins_mask = torch.cat(word_ins_masks, 0) + + return { + "word_ins": { + "out": word_ins_out, + "tgt": word_ins_tgt, + "mask": word_ins_mask, + "ls": self.args.label_smoothing, + "nll_loss": True, + }, + "length": { + "out": length_out, + "tgt": length_tgt, + "factor": self.decoder.length_loss_factor, + }, + } + + +@register_model_architecture( + "iterative_nonautoregressive_transformer", "iterative_nonautoregressive_transformer" +) +def inat_base_architecture(args): + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", False) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.dropout = getattr(args, "dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", False) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.apply_bert_init = getattr(args, "apply_bert_init", False) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + # --- special arguments --- + args.sg_length_pred = getattr(args, "sg_length_pred", False) + args.pred_length_offset = getattr(args, "pred_length_offset", False) + args.length_loss_factor = getattr(args, "length_loss_factor", 0.1) + args.ngram_predictor = getattr(args, "ngram_predictor", 1) + args.src_embedding_copy = getattr(args, "src_embedding_copy", False) + + args.train_step = getattr(args, "train_step", 4) + args.dae_ratio = getattr(args, "dae_ratio", 0.5) + args.stochastic_approx = getattr(args, "stochastic_approx", False) + + +@register_model_architecture( + "iterative_nonautoregressive_transformer", + "iterative_nonautoregressive_transformer_wmt_en_de", +) +def iter_nat_wmt_en_de(args): + inat_base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/levenshtein_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/levenshtein_transformer.py new file mode 100644 index 00000000..d60d3c52 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/levenshtein_transformer.py @@ -0,0 +1,510 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq.iterative_refinement_generator import DecoderOut +from fairseq.models import register_model, register_model_architecture +from fairseq.models.nat import FairseqNATDecoder, FairseqNATModel, ensemble_decoder +from fairseq.models.transformer import Embedding +from fairseq.modules import TransformerDecoderLayer +from fairseq.modules.transformer_sentence_encoder import init_bert_params + +from .levenshtein_utils import ( + _apply_del_words, + _apply_ins_masks, + _apply_ins_words, + _fill, + _get_del_targets, + _get_ins_targets, + _skip, + _skip_encoder_out, +) + + +@register_model("levenshtein_transformer") +class LevenshteinTransformerModel(FairseqNATModel): + @property + def allow_length_beam(self): + return False + + @staticmethod + def add_args(parser): + FairseqNATModel.add_args(parser) + parser.add_argument( + "--early-exit", + default="6,6,6", + type=str, + help="number of decoder layers before word_del, mask_ins, word_ins", + ) + parser.add_argument( + "--no-share-discriminator", + action="store_true", + help="separate parameters for discriminator", + ) + parser.add_argument( + "--no-share-maskpredictor", + action="store_true", + help="separate parameters for mask-predictor", + ) + parser.add_argument( + "--share-discriminator-maskpredictor", + action="store_true", + help="share the parameters for both mask-predictor and discriminator", + ) + parser.add_argument( + "--sampling-for-deletion", + action="store_true", + help="instead of argmax, use sampling to predict the tokens", + ) + + @classmethod + def build_decoder(cls, args, tgt_dict, embed_tokens): + decoder = LevenshteinTransformerDecoder(args, tgt_dict, embed_tokens) + if getattr(args, "apply_bert_init", False): + decoder.apply(init_bert_params) + return decoder + + def forward( + self, src_tokens, src_lengths, prev_output_tokens, tgt_tokens, **kwargs + ): + + assert tgt_tokens is not None, "forward function only supports training." + + # encoding + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + + # generate training labels for insertion + masked_tgt_masks, masked_tgt_tokens, mask_ins_targets = _get_ins_targets( + prev_output_tokens, tgt_tokens, self.pad, self.unk + ) + mask_ins_targets = mask_ins_targets.clamp(min=0, max=255) # for safe prediction + mask_ins_masks = prev_output_tokens[:, 1:].ne(self.pad) + + mask_ins_out, _ = self.decoder.forward_mask_ins( + normalize=False, + prev_output_tokens=prev_output_tokens, + encoder_out=encoder_out, + ) + word_ins_out, _ = self.decoder.forward_word_ins( + normalize=False, + prev_output_tokens=masked_tgt_tokens, + encoder_out=encoder_out, + ) + + # make online prediction + if self.decoder.sampling_for_deletion: + word_predictions = torch.multinomial( + F.softmax(word_ins_out, -1).view(-1, word_ins_out.size(-1)), 1 + ).view(word_ins_out.size(0), -1) + else: + word_predictions = F.log_softmax(word_ins_out, dim=-1).max(2)[1] + + word_predictions.masked_scatter_( + ~masked_tgt_masks, tgt_tokens[~masked_tgt_masks] + ) + + # generate training labels for deletion + word_del_targets = _get_del_targets(word_predictions, tgt_tokens, self.pad) + word_del_out, _ = self.decoder.forward_word_del( + normalize=False, + prev_output_tokens=word_predictions, + encoder_out=encoder_out, + ) + word_del_masks = word_predictions.ne(self.pad) + + return { + "mask_ins": { + "out": mask_ins_out, + "tgt": mask_ins_targets, + "mask": mask_ins_masks, + "ls": 0.01, + }, + "word_ins": { + "out": word_ins_out, + "tgt": tgt_tokens, + "mask": masked_tgt_masks, + "ls": self.args.label_smoothing, + "nll_loss": True, + }, + "word_del": { + "out": word_del_out, + "tgt": word_del_targets, + "mask": word_del_masks, + }, + } + + def forward_decoder( + self, decoder_out, encoder_out, eos_penalty=0.0, max_ratio=None, **kwargs + ): + + output_tokens = decoder_out.output_tokens + output_scores = decoder_out.output_scores + attn = decoder_out.attn + history = decoder_out.history + + bsz = output_tokens.size(0) + if max_ratio is None: + max_lens = torch.zeros_like(output_tokens).fill_(255) + else: + if not encoder_out["encoder_padding_mask"]: + max_src_len = encoder_out["encoder_out"].size(0) + src_lens = encoder_out["encoder_out"].new(bsz).fill_(max_src_len) + else: + src_lens = (~encoder_out["encoder_padding_mask"][0]).sum(1) + max_lens = (src_lens * max_ratio).clamp(min=10).long() + + # delete words + # do not delete tokens if it is + can_del_word = output_tokens.ne(self.pad).sum(1) > 2 + if can_del_word.sum() != 0: # we cannot delete, skip + word_del_score, word_del_attn = self.decoder.forward_word_del( + normalize=True, + prev_output_tokens=_skip(output_tokens, can_del_word), + encoder_out=_skip_encoder_out(self.encoder, encoder_out, can_del_word), + ) + word_del_pred = word_del_score.max(-1)[1].bool() + + _tokens, _scores, _attn = _apply_del_words( + output_tokens[can_del_word], + output_scores[can_del_word], + word_del_attn, + word_del_pred, + self.pad, + self.bos, + self.eos, + ) + output_tokens = _fill(output_tokens, can_del_word, _tokens, self.pad) + output_scores = _fill(output_scores, can_del_word, _scores, 0) + attn = _fill(attn, can_del_word, _attn, 0.0) + + if history is not None: + history.append(output_tokens.clone()) + + # insert placeholders + can_ins_mask = output_tokens.ne(self.pad).sum(1) < max_lens + if can_ins_mask.sum() != 0: + mask_ins_score, _ = self.decoder.forward_mask_ins( + normalize=True, + prev_output_tokens=_skip(output_tokens, can_ins_mask), + encoder_out=_skip_encoder_out(self.encoder, encoder_out, can_ins_mask), + ) + if eos_penalty > 0.0: + mask_ins_score[:, :, 0] = mask_ins_score[:, :, 0] - eos_penalty + mask_ins_pred = mask_ins_score.max(-1)[1] + mask_ins_pred = torch.min( + mask_ins_pred, max_lens[can_ins_mask, None].expand_as(mask_ins_pred) + ) + + _tokens, _scores = _apply_ins_masks( + output_tokens[can_ins_mask], + output_scores[can_ins_mask], + mask_ins_pred, + self.pad, + self.unk, + self.eos, + ) + output_tokens = _fill(output_tokens, can_ins_mask, _tokens, self.pad) + output_scores = _fill(output_scores, can_ins_mask, _scores, 0) + + if history is not None: + history.append(output_tokens.clone()) + + # insert words + can_ins_word = output_tokens.eq(self.unk).sum(1) > 0 + if can_ins_word.sum() != 0: + word_ins_score, word_ins_attn = self.decoder.forward_word_ins( + normalize=True, + prev_output_tokens=_skip(output_tokens, can_ins_word), + encoder_out=_skip_encoder_out(self.encoder, encoder_out, can_ins_word), + ) + word_ins_score, word_ins_pred = word_ins_score.max(-1) + _tokens, _scores = _apply_ins_words( + output_tokens[can_ins_word], + output_scores[can_ins_word], + word_ins_pred, + word_ins_score, + self.unk, + ) + + output_tokens = _fill(output_tokens, can_ins_word, _tokens, self.pad) + output_scores = _fill(output_scores, can_ins_word, _scores, 0) + attn = _fill(attn, can_ins_word, word_ins_attn, 0.0) + + if history is not None: + history.append(output_tokens.clone()) + + # delete some unnecessary paddings + cut_off = output_tokens.ne(self.pad).sum(1).max() + output_tokens = output_tokens[:, :cut_off] + output_scores = output_scores[:, :cut_off] + attn = None if attn is None else attn[:, :cut_off, :] + + return decoder_out._replace( + output_tokens=output_tokens, + output_scores=output_scores, + attn=attn, + history=history, + ) + + def initialize_output_tokens(self, encoder_out, src_tokens): + initial_output_tokens = src_tokens.new_zeros(src_tokens.size(0), 2) + initial_output_tokens[:, 0] = self.bos + initial_output_tokens[:, 1] = self.eos + + initial_output_scores = initial_output_tokens.new_zeros( + *initial_output_tokens.size() + ).type_as(encoder_out["encoder_out"][0]) + + return DecoderOut( + output_tokens=initial_output_tokens, + output_scores=initial_output_scores, + attn=None, + step=0, + max_step=0, + history=None, + ) + + +class LevenshteinTransformerDecoder(FairseqNATDecoder): + def __init__(self, args, dictionary, embed_tokens, no_encoder_attn=False): + super().__init__( + args, dictionary, embed_tokens, no_encoder_attn=no_encoder_attn + ) + self.dictionary = dictionary + self.bos = dictionary.bos() + self.unk = dictionary.unk() + self.eos = dictionary.eos() + self.sampling_for_deletion = getattr(args, "sampling_for_deletion", False) + self.embed_mask_ins = Embedding(256, self.output_embed_dim * 2, None) + self.embed_word_del = Embedding(2, self.output_embed_dim, None) + + # del_word, ins_mask, ins_word + self.early_exit = [int(i) for i in args.early_exit.split(",")] + assert len(self.early_exit) == 3 + + # copy layers for mask-predict/deletion + self.layers_msk = None + if getattr(args, "no_share_maskpredictor", False): + self.layers_msk = nn.ModuleList( + [ + TransformerDecoderLayer(args, no_encoder_attn) + for _ in range(self.early_exit[1]) + ] + ) + self.layers_del = None + if getattr(args, "no_share_discriminator", False): + self.layers_del = nn.ModuleList( + [ + TransformerDecoderLayer(args, no_encoder_attn) + for _ in range(self.early_exit[0]) + ] + ) + + if getattr(args, "share_discriminator_maskpredictor", False): + assert getattr( + args, "no_share_discriminator", False + ), "must set saperate discriminator" + self.layers_msk = self.layers_del + + def extract_features( + self, + prev_output_tokens, + encoder_out=None, + early_exit=None, + layers=None, + **unused + ): + """ + Similar to *forward* but only return features. + Inputs: + prev_output_tokens: Tensor(B, T) + encoder_out: a dictionary of hidden states and masks + + Returns: + tuple: + - the decoder's features of shape `(batch, tgt_len, embed_dim)` + - a dictionary with any model-specific outputs + the LevenshteinTransformer decoder has full-attention to all generated tokens + """ + # embed positions + positions = ( + self.embed_positions(prev_output_tokens) + if self.embed_positions is not None + else None + ) + + # embed tokens and positions + x = self.embed_scale * self.embed_tokens(prev_output_tokens) + if self.project_in_dim is not None: + x = self.project_in_dim(x) + + if positions is not None: + x += positions + x = self.dropout_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + attn = None + inner_states = [x] + + # decoder layers + decoder_padding_mask = prev_output_tokens.eq(self.padding_idx) + layers = self.layers if layers is None else layers + early_exit = len(layers) if early_exit is None else early_exit + for _, layer in enumerate(layers[:early_exit]): + x, attn, _ = layer( + x, + encoder_out["encoder_out"][0] + if (encoder_out is not None and len(encoder_out["encoder_out"]) > 0) + else None, + encoder_out["encoder_padding_mask"][0] + if ( + encoder_out is not None + and len(encoder_out["encoder_padding_mask"]) > 0 + ) + else None, + self_attn_mask=None, + self_attn_padding_mask=decoder_padding_mask, + ) + inner_states.append(x) + + if self.layer_norm: + x = self.layer_norm(x) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + if self.project_out_dim is not None: + x = self.project_out_dim(x) + + return x, {"attn": attn, "inner_states": inner_states} + + @ensemble_decoder + def forward_mask_ins(self, normalize, encoder_out, prev_output_tokens, **unused): + features, extra = self.extract_features( + prev_output_tokens, + encoder_out=encoder_out, + early_exit=self.early_exit[1], + layers=self.layers_msk, + **unused + ) + features_cat = torch.cat([features[:, :-1, :], features[:, 1:, :]], 2) + decoder_out = F.linear(features_cat, self.embed_mask_ins.weight) + if normalize: + return F.log_softmax(decoder_out, -1), extra["attn"] + return decoder_out, extra["attn"] + + @ensemble_decoder + def forward_word_ins(self, normalize, encoder_out, prev_output_tokens, **unused): + features, extra = self.extract_features( + prev_output_tokens, + encoder_out=encoder_out, + early_exit=self.early_exit[2], + layers=self.layers, + **unused + ) + decoder_out = self.output_layer(features) + if normalize: + return F.log_softmax(decoder_out, -1), extra["attn"] + return decoder_out, extra["attn"] + + @ensemble_decoder + def forward_word_del(self, normalize, encoder_out, prev_output_tokens, **unused): + features, extra = self.extract_features( + prev_output_tokens, + encoder_out=encoder_out, + early_exit=self.early_exit[0], + layers=self.layers_del, + **unused + ) + decoder_out = F.linear(features, self.embed_word_del.weight) + if normalize: + return F.log_softmax(decoder_out, -1), extra["attn"] + return decoder_out, extra["attn"] + + +@register_model_architecture("levenshtein_transformer", "levenshtein_transformer") +def levenshtein_base_architecture(args): + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", False) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.dropout = getattr(args, "dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", False) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.apply_bert_init = getattr(args, "apply_bert_init", False) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.sampling_for_deletion = getattr(args, "sampling_for_deletion", False) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + args.early_exit = getattr(args, "early_exit", "6,6,6") + args.no_share_discriminator = getattr(args, "no_share_discriminator", False) + args.no_share_maskpredictor = getattr(args, "no_share_maskpredictor", False) + args.share_discriminator_maskpredictor = getattr( + args, "share_discriminator_maskpredictor", False + ) + args.no_share_last_layer = getattr(args, "no_share_last_layer", False) + + +@register_model_architecture( + "levenshtein_transformer", "levenshtein_transformer_wmt_en_de" +) +def levenshtein_transformer_wmt_en_de(args): + levenshtein_base_architecture(args) + + +# similar parameters used in the "Attention Is All You Need" paper (Vaswani et al., 2017) +@register_model_architecture( + "levenshtein_transformer", "levenshtein_transformer_vaswani_wmt_en_de_big" +) +def levenshtein_transformer_vaswani_wmt_en_de_big(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4096) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 16) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 1024) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 4096) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 16) + args.dropout = getattr(args, "dropout", 0.3) + levenshtein_base_architecture(args) + + +# default parameters used in tensor2tensor implementation +@register_model_architecture( + "levenshtein_transformer", "levenshtein_transformer_wmt_en_de_big" +) +def levenshtein_transformer_wmt_en_de_big_t2t(args): + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", True) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", True) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.activation_dropout = getattr(args, "activation_dropout", 0.1) + levenshtein_transformer_vaswani_wmt_en_de_big(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/levenshtein_utils.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/levenshtein_utils.py new file mode 100644 index 00000000..375a98c2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/levenshtein_utils.py @@ -0,0 +1,293 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from fairseq.utils import new_arange + + +# -------------- Helper Functions --------------------------------------------------- # + + +def load_libnat(): + try: + from fairseq import libnat_cuda + + return libnat_cuda, True + + except ImportError as e: + print(str(e) + "... fall back to CPU version") + + try: + from fairseq import libnat + + return libnat, False + + except ImportError as e: + import sys + + sys.stderr.write( + "ERROR: missing libnat_cuda. run `python setup.py build_ext --inplace`\n" + ) + raise e + + +def _get_ins_targets(in_tokens, out_tokens, padding_idx, unk_idx): + libnat, use_cuda = load_libnat() + + def _get_ins_targets_cuda(in_tokens, out_tokens, padding_idx, unk_idx): + in_masks = in_tokens.ne(padding_idx) + out_masks = out_tokens.ne(padding_idx) + mask_ins_targets, masked_tgt_masks = libnat.generate_insertion_labels( + out_tokens.int(), + libnat.levenshtein_distance( + in_tokens.int(), + out_tokens.int(), + in_masks.sum(1).int(), + out_masks.sum(1).int(), + ), + ) + masked_tgt_masks = masked_tgt_masks.bool() & out_masks + mask_ins_targets = mask_ins_targets.type_as(in_tokens)[ + :, 1 : in_masks.size(1) + ].masked_fill_(~in_masks[:, 1:], 0) + masked_tgt_tokens = out_tokens.masked_fill(masked_tgt_masks, unk_idx) + return masked_tgt_masks, masked_tgt_tokens, mask_ins_targets + + def _get_ins_targets_cpu(in_tokens, out_tokens, padding_idx, unk_idx): + in_seq_len, out_seq_len = in_tokens.size(1), out_tokens.size(1) + + in_tokens_list = [ + [t for t in s if t != padding_idx] for i, s in enumerate(in_tokens.tolist()) + ] + out_tokens_list = [ + [t for t in s if t != padding_idx] + for i, s in enumerate(out_tokens.tolist()) + ] + + full_labels = libnat.suggested_ed2_path( + in_tokens_list, out_tokens_list, padding_idx + ) + mask_inputs = [ + [len(c) if c[0] != padding_idx else 0 for c in a[:-1]] for a in full_labels + ] + + # generate labels + masked_tgt_masks = [] + for mask_input in mask_inputs: + mask_label = [] + for beam_size in mask_input[1:-1]: # HACK 1:-1 + mask_label += [0] + [1 for _ in range(beam_size)] + masked_tgt_masks.append( + mask_label + [0 for _ in range(out_seq_len - len(mask_label))] + ) + mask_ins_targets = [ + mask_input[1:-1] + + [0 for _ in range(in_seq_len - 1 - len(mask_input[1:-1]))] + for mask_input in mask_inputs + ] + + # transform to tensor + masked_tgt_masks = torch.tensor( + masked_tgt_masks, device=out_tokens.device + ).bool() + mask_ins_targets = torch.tensor(mask_ins_targets, device=in_tokens.device) + masked_tgt_tokens = out_tokens.masked_fill(masked_tgt_masks, unk_idx) + return masked_tgt_masks, masked_tgt_tokens, mask_ins_targets + + if use_cuda: + return _get_ins_targets_cuda(in_tokens, out_tokens, padding_idx, unk_idx) + return _get_ins_targets_cpu(in_tokens, out_tokens, padding_idx, unk_idx) + + +def _get_del_targets(in_tokens, out_tokens, padding_idx): + libnat, use_cuda = load_libnat() + + def _get_del_targets_cuda(in_tokens, out_tokens, padding_idx): + in_masks = in_tokens.ne(padding_idx) + out_masks = out_tokens.ne(padding_idx) + + word_del_targets = libnat.generate_deletion_labels( + in_tokens.int(), + libnat.levenshtein_distance( + in_tokens.int(), + out_tokens.int(), + in_masks.sum(1).int(), + out_masks.sum(1).int(), + ), + ) + word_del_targets = word_del_targets.type_as(in_tokens).masked_fill_( + ~in_masks, 0 + ) + return word_del_targets + + def _get_del_targets_cpu(in_tokens, out_tokens, padding_idx): + out_seq_len = out_tokens.size(1) + with torch.cuda.device_of(in_tokens): + in_tokens_list = [ + [t for t in s if t != padding_idx] + for i, s in enumerate(in_tokens.tolist()) + ] + out_tokens_list = [ + [t for t in s if t != padding_idx] + for i, s in enumerate(out_tokens.tolist()) + ] + + full_labels = libnat.suggested_ed2_path( + in_tokens_list, out_tokens_list, padding_idx + ) + word_del_targets = [b[-1] for b in full_labels] + word_del_targets = [ + labels + [0 for _ in range(out_seq_len - len(labels))] + for labels in word_del_targets + ] + + # transform to tensor + word_del_targets = torch.tensor(word_del_targets, device=out_tokens.device) + return word_del_targets + + if use_cuda: + return _get_del_targets_cuda(in_tokens, out_tokens, padding_idx) + return _get_del_targets_cpu(in_tokens, out_tokens, padding_idx) + + +def _apply_ins_masks( + in_tokens, in_scores, mask_ins_pred, padding_idx, unk_idx, eos_idx +): + + in_masks = in_tokens.ne(padding_idx) + in_lengths = in_masks.sum(1) + + # HACK: hacky way to shift all the paddings to eos first. + in_tokens.masked_fill_(~in_masks, eos_idx) + mask_ins_pred.masked_fill_(~in_masks[:, 1:], 0) + + out_lengths = in_lengths + mask_ins_pred.sum(1) + out_max_len = out_lengths.max() + out_masks = new_arange(out_lengths, out_max_len)[None, :] < out_lengths[:, None] + + reordering = (mask_ins_pred + in_masks[:, 1:].long()).cumsum(1) + out_tokens = ( + in_tokens.new_zeros(in_tokens.size(0), out_max_len) + .fill_(padding_idx) + .masked_fill_(out_masks, unk_idx) + ) + out_tokens[:, 0] = in_tokens[:, 0] + out_tokens.scatter_(1, reordering, in_tokens[:, 1:]) + + out_scores = None + if in_scores is not None: + in_scores.masked_fill_(~in_masks, 0) + out_scores = in_scores.new_zeros(*out_tokens.size()) + out_scores[:, 0] = in_scores[:, 0] + out_scores.scatter_(1, reordering, in_scores[:, 1:]) + + return out_tokens, out_scores + + +def _apply_ins_words(in_tokens, in_scores, word_ins_pred, word_ins_scores, unk_idx): + word_ins_masks = in_tokens.eq(unk_idx) + out_tokens = in_tokens.masked_scatter(word_ins_masks, word_ins_pred[word_ins_masks]) + + if in_scores is not None: + out_scores = in_scores.masked_scatter( + word_ins_masks, word_ins_scores[word_ins_masks] + ) + else: + out_scores = None + + return out_tokens, out_scores + + +def _apply_del_words( + in_tokens, in_scores, in_attn, word_del_pred, padding_idx, bos_idx, eos_idx +): + # apply deletion to a tensor + in_masks = in_tokens.ne(padding_idx) + bos_eos_masks = in_tokens.eq(bos_idx) | in_tokens.eq(eos_idx) + + max_len = in_tokens.size(1) + word_del_pred.masked_fill_(~in_masks, 1) + word_del_pred.masked_fill_(bos_eos_masks, 0) + + reordering = new_arange(in_tokens).masked_fill_(word_del_pred, max_len).sort(1)[1] + + out_tokens = in_tokens.masked_fill(word_del_pred, padding_idx).gather(1, reordering) + + out_scores = None + if in_scores is not None: + out_scores = in_scores.masked_fill(word_del_pred, 0).gather(1, reordering) + + out_attn = None + if in_attn is not None: + _mask = word_del_pred[:, :, None].expand_as(in_attn) + _reordering = reordering[:, :, None].expand_as(in_attn) + out_attn = in_attn.masked_fill(_mask, 0.0).gather(1, _reordering) + + return out_tokens, out_scores, out_attn + + +def _skip(x, mask): + """ + Getting sliced (dim=0) tensor by mask. Supporting tensor and list/dict of tensors. + """ + if isinstance(x, int): + return x + + if x is None: + return None + + if isinstance(x, torch.Tensor): + if x.size(0) == mask.size(0): + return x[mask] + elif x.size(1) == mask.size(0): + return x[:, mask] + + if isinstance(x, list): + return [_skip(x_i, mask) for x_i in x] + + if isinstance(x, dict): + return {k: _skip(v, mask) for k, v in x.items()} + + raise NotImplementedError + + +def _skip_encoder_out(encoder, encoder_out, mask): + if not mask.any(): + return encoder_out + else: + return encoder.reorder_encoder_out( + encoder_out, mask.nonzero(as_tuple=False).squeeze() + ) + + +def _fill(x, mask, y, padding_idx): + """ + Filling tensor x with y at masked positions (dim=0). + """ + if x is None: + return y + assert x.dim() == y.dim() and mask.size(0) == x.size(0) + assert x.dim() == 2 or (x.dim() == 3 and x.size(2) == y.size(2)) + n_selected = mask.sum() + assert n_selected == y.size(0) + + if n_selected == x.size(0): + return y + + if x.size(1) < y.size(1): + dims = [x.size(0), y.size(1) - x.size(1)] + if x.dim() == 3: + dims.append(x.size(2)) + x = torch.cat([x, x.new_zeros(*dims).fill_(padding_idx)], 1) + x[mask] = y + elif x.size(1) > y.size(1): + x[mask] = padding_idx + if x.dim() == 2: + x[mask, : y.size(1)] = y + else: + x[mask, : y.size(1), :] = y + else: + x[mask] = y + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/nat_crf_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/nat_crf_transformer.py new file mode 100644 index 00000000..d4b3cd93 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/nat_crf_transformer.py @@ -0,0 +1,121 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from fairseq.models import register_model, register_model_architecture +from fairseq.models.nat import NATransformerModel, base_architecture +from fairseq.modules import DynamicCRF + + +@register_model("nacrf_transformer") +class NACRFTransformerModel(NATransformerModel): + def __init__(self, args, encoder, decoder): + super().__init__(args, encoder, decoder) + self.crf_layer = DynamicCRF( + num_embedding=len(self.tgt_dict), + low_rank=args.crf_lowrank_approx, + beam_size=args.crf_beam_approx, + ) + + @property + def allow_ensemble(self): + return False + + @staticmethod + def add_args(parser): + NATransformerModel.add_args(parser) + parser.add_argument( + "--crf-lowrank-approx", + type=int, + help="the dimension of low-rank approximation of transition", + ) + parser.add_argument( + "--crf-beam-approx", + type=int, + help="the beam size for apporixmating the normalizing factor", + ) + parser.add_argument( + "--word-ins-loss-factor", + type=float, + help="weights on NAT loss used to co-training with CRF loss.", + ) + + def forward( + self, src_tokens, src_lengths, prev_output_tokens, tgt_tokens, **kwargs + ): + # encoding + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + + # length prediction + length_out = self.decoder.forward_length( + normalize=False, encoder_out=encoder_out + ) + length_tgt = self.decoder.forward_length_prediction( + length_out, encoder_out, tgt_tokens + ) + + # decoding + word_ins_out = self.decoder( + normalize=False, + prev_output_tokens=prev_output_tokens, + encoder_out=encoder_out, + ) + word_ins_tgt, word_ins_mask = tgt_tokens, tgt_tokens.ne(self.pad) + + # compute the log-likelihood of CRF + crf_nll = -self.crf_layer(word_ins_out, word_ins_tgt, word_ins_mask) + crf_nll = (crf_nll / word_ins_mask.type_as(crf_nll).sum(-1)).mean() + + return { + "word_ins": { + "out": word_ins_out, + "tgt": word_ins_tgt, + "mask": word_ins_mask, + "ls": self.args.label_smoothing, + "nll_loss": True, + "factor": self.args.word_ins_loss_factor, + }, + "word_crf": {"loss": crf_nll}, + "length": { + "out": length_out, + "tgt": length_tgt, + "factor": self.decoder.length_loss_factor, + }, + } + + def forward_decoder(self, decoder_out, encoder_out, decoding_format=None, **kwargs): + output_tokens = decoder_out.output_tokens + output_scores = decoder_out.output_scores + history = decoder_out.history + + # execute the decoder and get emission scores + output_masks = output_tokens.ne(self.pad) + word_ins_out = self.decoder( + normalize=False, prev_output_tokens=output_tokens, encoder_out=encoder_out + ) + + # run viterbi decoding through CRF + _scores, _tokens = self.crf_layer.forward_decoder(word_ins_out, output_masks) + output_tokens.masked_scatter_(output_masks, _tokens[output_masks]) + output_scores.masked_scatter_(output_masks, _scores[output_masks]) + if history is not None: + history.append(output_tokens.clone()) + + return decoder_out._replace( + output_tokens=output_tokens, + output_scores=output_scores, + attn=None, + history=history, + ) + + +@register_model_architecture("nacrf_transformer", "nacrf_transformer") +def nacrf_base_architecture(args): + args.crf_lowrank_approx = getattr(args, "crf_lowrank_approx", 32) + args.crf_beam_approx = getattr(args, "crf_beam_approx", 64) + args.word_ins_loss_factor = getattr(args, "word_ins_loss_factor", 0.5) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", True) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", True) + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/nonautoregressive_ensembles.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/nonautoregressive_ensembles.py new file mode 100644 index 00000000..0a0221f9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/nonautoregressive_ensembles.py @@ -0,0 +1,254 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch +import torch.nn.functional as F +from fairseq.models.nat import ( + _apply_del_words, + _apply_ins_masks, + _apply_ins_words, + _fill, + _skip, + _skip_encoder_out, +) + + +class _EnsembleModelEncoder(object): + def __init__(self, models): + self.models = models + + def reorder_encoder_out(self, encoder_outs, new_order): + encoder_outs = [ + model.encoder.reorder_encoder_out(encoder_out, new_order) + for model, encoder_out in zip(self.models, encoder_outs) + ] + return encoder_outs + + +class BasicEnsembleModel(torch.nn.Module): + """A wrapper around an ensemble of models.""" + + def __init__(self, models): + super().__init__() + self.models = torch.nn.ModuleList(models) + self.bos = self.models[0].decoder.dictionary.bos() + self.eos = self.models[0].decoder.dictionary.eos() + self.pad = self.models[0].decoder.dictionary.pad() + self.unk = self.models[0].decoder.dictionary.unk() + self.encoder = _EnsembleModelEncoder(self.models) + + def has_encoder(self): + return hasattr(self.models[0], "encoder") + + def max_decoder_positions(self): + return min(m.max_decoder_positions() for m in self.models) + + @torch.no_grad() + def forward_encoder(self, encoder_input): + if not self.has_encoder(): + return None + return [model.forward_encoder(encoder_input) for model in self.models] + + @torch.no_grad() + def forward_decoder(self, *inputs): + raise NotImplementedError + + def initialize_output_tokens(self, *inputs): + raise NotImplementedError + + +class EnsembleLevT(BasicEnsembleModel): + """A wrapper around an ensemble of models.""" + + def __init__(self, models): + super().__init__(models) + + @torch.no_grad() + def forward_decoder( + self, decoder_out, encoder_outs, eos_penalty=0.0, max_ratio=None, **kwargs + ): + # LevT ensembling + # A pipeline of three steps: deletion, placeholder, and word insertion. + # We need to average scores in each step in a pipeline way because of dependence. + # deletion + output_tokens = decoder_out.output_tokens + output_scores = decoder_out.output_scores + attn = decoder_out.attn + + bsz = output_tokens.size(0) + if max_ratio is None: + max_lens = output_tokens.new().fill_(255) + else: + if not encoder_outs[0]["encoder_padding_mask"]: + src_lens = ( + encoder_outs[0]["encoder_out"][0] + .new(bsz) + .fill_(encoder_outs[0]["encoder_out"][0].size(1)) + ) + else: + src_lens = (~encoder_outs[0]["encoder_padding_mask"][0]).sum(1) + max_lens = (src_lens * max_ratio).clamp(min=10).long() + + # delete words + # do not delete tokens if it is + can_del_word = output_tokens.ne(self.pad).sum(1) > 2 + if can_del_word.sum() != 0: # we cannot delete, skip + output_tokens, output_scores, attn = self.forward_word_del( + encoder_outs, + output_tokens, + output_scores, + attn, + can_del_word, + ) + + # insert placeholders + can_ins_mask = output_tokens.ne(self.pad).sum(1) < max_lens + if can_ins_mask.sum() != 0: + output_tokens, output_scores = self.forward_mask_ins( + encoder_outs, + output_tokens, + output_scores, + can_ins_mask, + eos_penalty, + max_lens, + ) + + # insert words + can_ins_word = output_tokens.eq(self.unk).sum(1) > 0 + if can_ins_word.sum() != 0: + output_tokens, output_scores, attn = self.forward_word_ins( + encoder_outs, + output_tokens, + output_scores, + attn, + can_ins_word, + ) + + # delete some unnecessary paddings + cut_off = output_tokens.ne(self.pad).sum(1).max() + output_tokens = output_tokens[:, :cut_off] + output_scores = output_scores[:, :cut_off] + attn = None if attn is None else attn[:, :cut_off, :] + return decoder_out._replace( + output_tokens=output_tokens, + output_scores=output_scores, + attn=attn, + history=None, + ) + + def forward_word_del( + self, encoder_outs, output_tokens, output_scores, attn, can_del_word + ): + word_del_score_avg = [] + word_del_attn_avg = [] + for model, encoder_out in zip(self.models, encoder_outs): + word_del_out, word_del_attn = model.decoder.forward_word_del( + _skip(output_tokens, can_del_word), + _skip_encoder_out(model.encoder, encoder_out, can_del_word), + ) + word_del_score = F.log_softmax(word_del_out, 2) + word_del_score_avg.append(word_del_score) + word_del_attn_avg.append(word_del_attn) + word_del_score_avg = torch.logsumexp( + torch.stack(word_del_score_avg, dim=0), dim=0 + ) - math.log(len(self.models)) + word_del_pred = word_del_score_avg.max(-1)[1].bool() + if word_del_attn_avg[0] is not None: + word_del_attn_avg = torch.stack(word_del_attn_avg, dim=0) / len(self.models) + else: + word_del_attn_avg = None + + _tokens, _scores, _attn = _apply_del_words( + output_tokens[can_del_word], + output_scores[can_del_word], + word_del_attn_avg, + word_del_pred, + self.pad, + self.bos, + self.eos, + ) + output_tokens = _fill(output_tokens, can_del_word, _tokens, self.pad) + output_scores = _fill(output_scores, can_del_word, _scores, 0) + attn = _fill(attn, can_del_word, _attn, 0.0) + return output_tokens, output_scores, attn + + def forward_mask_ins( + self, + encoder_outs, + output_tokens, + output_scores, + can_ins_mask, + eos_penalty, + max_lens, + ): + mask_ins_score_avg = [] + for model, encoder_out in zip(self.models, encoder_outs): + mask_ins_out, _ = model.decoder.forward_mask_ins( + _skip(output_tokens, can_ins_mask), + _skip_encoder_out(model.encoder, encoder_out, can_ins_mask), + ) + mask_ins_score = F.log_softmax(mask_ins_out, 2) + if eos_penalty > 0.0: + mask_ins_score[:, :, 0] -= eos_penalty + mask_ins_score_avg.append(mask_ins_score) + mask_ins_score_avg = torch.logsumexp( + torch.stack(mask_ins_score_avg, dim=0), dim=0 + ) - math.log(len(self.models)) + mask_ins_pred = mask_ins_score_avg.max(-1)[1] + mask_ins_pred = torch.min( + mask_ins_pred, max_lens[can_ins_mask, None].expand_as(mask_ins_pred) + ) + _tokens, _scores = _apply_ins_masks( + output_tokens[can_ins_mask], + output_scores[can_ins_mask], + mask_ins_pred, + self.pad, + self.unk, + self.eos, + ) + output_tokens = _fill(output_tokens, can_ins_mask, _tokens, self.pad) + output_scores = _fill(output_scores, can_ins_mask, _scores, 0) + return output_tokens, output_scores + + def forward_word_ins( + self, encoder_outs, output_tokens, output_scores, attn, can_ins_word + ): + word_ins_score_avg = [] + word_ins_attn_avg = [] + for model, encoder_out in zip(self.models, encoder_outs): + word_ins_out, word_ins_attn = model.decoder.forward_word_ins( + _skip(output_tokens, can_ins_word), + _skip_encoder_out(model.encoder, encoder_out, can_ins_word), + ) + word_ins_score = F.log_softmax(word_ins_out, 2) + word_ins_score_avg.append(word_ins_score) + word_ins_attn_avg.append(word_ins_attn) + word_ins_score_avg = torch.logsumexp( + torch.stack(word_ins_score_avg, dim=0), dim=0 + ) - math.log(len(self.models)) + if word_ins_attn_avg[0] is not None: + word_ins_attn_avg = torch.stack(word_ins_attn_avg, dim=0) / len(self.models) + else: + word_ins_attn_avg = None + word_ins_score_max, word_ins_pred = word_ins_score_avg.max(-1) + + _tokens, _scores = _apply_ins_words( + output_tokens[can_ins_word], + output_scores[can_ins_word], + word_ins_pred, + word_ins_score_max, + self.unk, + ) + + output_tokens = _fill(output_tokens, can_ins_word, _tokens, self.pad) + output_scores = _fill(output_scores, can_ins_word, _scores, 0) + attn = _fill(attn, can_ins_word, word_ins_attn, 0.0) + return output_tokens, output_scores, attn + + def initialize_output_tokens(self, encoder_outs, src_tokens): + # LevT doesn't do length prediction. + return self.models[0].initialize_output_tokens(encoder_outs[0], src_tokens) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/nat/nonautoregressive_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/nat/nonautoregressive_transformer.py new file mode 100644 index 00000000..d114202d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/nat/nonautoregressive_transformer.py @@ -0,0 +1,456 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn.functional as F +from fairseq import utils +from fairseq.iterative_refinement_generator import DecoderOut +from fairseq.models import register_model, register_model_architecture +from fairseq.models.nat import FairseqNATDecoder, FairseqNATModel, ensemble_decoder +from fairseq.models.transformer import Embedding +from fairseq.modules.transformer_sentence_encoder import init_bert_params + + +def _mean_pooling(enc_feats, src_masks): + # enc_feats: T x B x C + # src_masks: B x T or None + if src_masks is None: + enc_feats = enc_feats.mean(0) + else: + src_masks = (~src_masks).transpose(0, 1).type_as(enc_feats) + enc_feats = ( + (enc_feats / src_masks.sum(0)[None, :, None]) * src_masks[:, :, None] + ).sum(0) + return enc_feats + + +def _argmax(x, dim): + return (x == x.max(dim, keepdim=True)[0]).type_as(x) + + +def _uniform_assignment(src_lens, trg_lens): + max_trg_len = trg_lens.max() + steps = (src_lens.float() - 1) / (trg_lens.float() - 1) # step-size + # max_trg_len + index_t = utils.new_arange(trg_lens, max_trg_len).float() + index_t = steps[:, None] * index_t[None, :] # batch_size X max_trg_len + index_t = torch.round(index_t).long().detach() + return index_t + + +@register_model("nonautoregressive_transformer") +class NATransformerModel(FairseqNATModel): + @property + def allow_length_beam(self): + return True + + @staticmethod + def add_args(parser): + FairseqNATModel.add_args(parser) + + # length prediction + parser.add_argument( + "--src-embedding-copy", + action="store_true", + help="copy encoder word embeddings as the initial input of the decoder", + ) + parser.add_argument( + "--pred-length-offset", + action="store_true", + help="predicting the length difference between the target and source sentences", + ) + parser.add_argument( + "--sg-length-pred", + action="store_true", + help="stop the gradients back-propagated from the length predictor", + ) + parser.add_argument( + "--length-loss-factor", + type=float, + help="weights on the length prediction loss", + ) + + @classmethod + def build_decoder(cls, args, tgt_dict, embed_tokens): + decoder = NATransformerDecoder(args, tgt_dict, embed_tokens) + if getattr(args, "apply_bert_init", False): + decoder.apply(init_bert_params) + return decoder + + def forward( + self, src_tokens, src_lengths, prev_output_tokens, tgt_tokens, **kwargs + ): + # encoding + encoder_out = self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + + # length prediction + length_out = self.decoder.forward_length( + normalize=False, encoder_out=encoder_out + ) + length_tgt = self.decoder.forward_length_prediction( + length_out, encoder_out, tgt_tokens + ) + + # decoding + word_ins_out = self.decoder( + normalize=False, + prev_output_tokens=prev_output_tokens, + encoder_out=encoder_out, + ) + + return { + "word_ins": { + "out": word_ins_out, + "tgt": tgt_tokens, + "mask": tgt_tokens.ne(self.pad), + "ls": self.args.label_smoothing, + "nll_loss": True, + }, + "length": { + "out": length_out, + "tgt": length_tgt, + "factor": self.decoder.length_loss_factor, + }, + } + + def forward_decoder(self, decoder_out, encoder_out, decoding_format=None, **kwargs): + step = decoder_out.step + output_tokens = decoder_out.output_tokens + output_scores = decoder_out.output_scores + history = decoder_out.history + + # execute the decoder + output_masks = output_tokens.ne(self.pad) + _scores, _tokens = self.decoder( + normalize=True, + prev_output_tokens=output_tokens, + encoder_out=encoder_out, + step=step, + ).max(-1) + + output_tokens.masked_scatter_(output_masks, _tokens[output_masks]) + output_scores.masked_scatter_(output_masks, _scores[output_masks]) + if history is not None: + history.append(output_tokens.clone()) + + return decoder_out._replace( + output_tokens=output_tokens, + output_scores=output_scores, + attn=None, + history=history, + ) + + def initialize_output_tokens(self, encoder_out, src_tokens): + # length prediction + length_tgt = self.decoder.forward_length_prediction( + self.decoder.forward_length(normalize=True, encoder_out=encoder_out), + encoder_out=encoder_out, + ) + + max_length = length_tgt.clamp_(min=2).max() + idx_length = utils.new_arange(src_tokens, max_length) + + initial_output_tokens = src_tokens.new_zeros( + src_tokens.size(0), max_length + ).fill_(self.pad) + initial_output_tokens.masked_fill_( + idx_length[None, :] < length_tgt[:, None], self.unk + ) + initial_output_tokens[:, 0] = self.bos + initial_output_tokens.scatter_(1, length_tgt[:, None] - 1, self.eos) + + initial_output_scores = initial_output_tokens.new_zeros( + *initial_output_tokens.size() + ).type_as(encoder_out["encoder_out"][0]) + + return DecoderOut( + output_tokens=initial_output_tokens, + output_scores=initial_output_scores, + attn=None, + step=0, + max_step=0, + history=None, + ) + + def regenerate_length_beam(self, decoder_out, beam_size): + output_tokens = decoder_out.output_tokens + length_tgt = output_tokens.ne(self.pad).sum(1) + length_tgt = ( + length_tgt[:, None] + + utils.new_arange(length_tgt, 1, beam_size) + - beam_size // 2 + ) + length_tgt = length_tgt.view(-1).clamp_(min=2) + max_length = length_tgt.max() + idx_length = utils.new_arange(length_tgt, max_length) + + initial_output_tokens = output_tokens.new_zeros( + length_tgt.size(0), max_length + ).fill_(self.pad) + initial_output_tokens.masked_fill_( + idx_length[None, :] < length_tgt[:, None], self.unk + ) + initial_output_tokens[:, 0] = self.bos + initial_output_tokens.scatter_(1, length_tgt[:, None] - 1, self.eos) + + initial_output_scores = initial_output_tokens.new_zeros( + *initial_output_tokens.size() + ).type_as(decoder_out.output_scores) + + return decoder_out._replace( + output_tokens=initial_output_tokens, output_scores=initial_output_scores + ) + + +class NATransformerDecoder(FairseqNATDecoder): + def __init__(self, args, dictionary, embed_tokens, no_encoder_attn=False): + super().__init__( + args, dictionary, embed_tokens, no_encoder_attn=no_encoder_attn + ) + self.dictionary = dictionary + self.bos = dictionary.bos() + self.unk = dictionary.unk() + self.eos = dictionary.eos() + + self.encoder_embed_dim = args.encoder_embed_dim + self.sg_length_pred = getattr(args, "sg_length_pred", False) + self.pred_length_offset = getattr(args, "pred_length_offset", False) + self.length_loss_factor = getattr(args, "length_loss_factor", 0.1) + self.src_embedding_copy = getattr(args, "src_embedding_copy", False) + self.embed_length = Embedding(256, self.encoder_embed_dim, None) + + @ensemble_decoder + def forward(self, normalize, encoder_out, prev_output_tokens, step=0, **unused): + features, _ = self.extract_features( + prev_output_tokens, + encoder_out=encoder_out, + embedding_copy=(step == 0) & self.src_embedding_copy, + ) + decoder_out = self.output_layer(features) + return F.log_softmax(decoder_out, -1) if normalize else decoder_out + + @ensemble_decoder + def forward_length(self, normalize, encoder_out): + enc_feats = encoder_out["encoder_out"][0] # T x B x C + if len(encoder_out["encoder_padding_mask"]) > 0: + src_masks = encoder_out["encoder_padding_mask"][0] # B x T + else: + src_masks = None + enc_feats = _mean_pooling(enc_feats, src_masks) + if self.sg_length_pred: + enc_feats = enc_feats.detach() + length_out = F.linear(enc_feats, self.embed_length.weight) + return F.log_softmax(length_out, -1) if normalize else length_out + + def extract_features( + self, + prev_output_tokens, + encoder_out=None, + early_exit=None, + embedding_copy=False, + **unused + ): + """ + Similar to *forward* but only return features. + + Inputs: + prev_output_tokens: Tensor(B, T) + encoder_out: a dictionary of hidden states and masks + + Returns: + tuple: + - the decoder's features of shape `(batch, tgt_len, embed_dim)` + - a dictionary with any model-specific outputs + the LevenshteinTransformer decoder has full-attention to all generated tokens + """ + # embedding + if embedding_copy: + src_embd = encoder_out["encoder_embedding"][0] + if len(encoder_out["encoder_padding_mask"]) > 0: + src_mask = encoder_out["encoder_padding_mask"][0] + else: + src_mask = None + src_mask = ( + ~src_mask + if src_mask is not None + else prev_output_tokens.new_ones(*src_embd.size()[:2]).bool() + ) + + x, decoder_padding_mask = self.forward_embedding( + prev_output_tokens, + self.forward_copying_source( + src_embd, src_mask, prev_output_tokens.ne(self.padding_idx) + ), + ) + + else: + + x, decoder_padding_mask = self.forward_embedding(prev_output_tokens) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + attn = None + inner_states = [x] + + # decoder layers + for i, layer in enumerate(self.layers): + + # early exit from the decoder. + if (early_exit is not None) and (i >= early_exit): + break + + x, attn, _ = layer( + x, + encoder_out["encoder_out"][0] + if (encoder_out is not None and len(encoder_out["encoder_out"]) > 0) + else None, + encoder_out["encoder_padding_mask"][0] + if ( + encoder_out is not None + and len(encoder_out["encoder_padding_mask"]) > 0 + ) + else None, + self_attn_mask=None, + self_attn_padding_mask=decoder_padding_mask, + ) + inner_states.append(x) + + if self.layer_norm: + x = self.layer_norm(x) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + if self.project_out_dim is not None: + x = self.project_out_dim(x) + + return x, {"attn": attn, "inner_states": inner_states} + + def forward_embedding(self, prev_output_tokens, states=None): + # embed positions + positions = ( + self.embed_positions(prev_output_tokens) + if self.embed_positions is not None + else None + ) + + # embed tokens and positions + if states is None: + x = self.embed_scale * self.embed_tokens(prev_output_tokens) + if self.project_in_dim is not None: + x = self.project_in_dim(x) + else: + x = states + + if positions is not None: + x += positions + x = self.dropout_module(x) + decoder_padding_mask = prev_output_tokens.eq(self.padding_idx) + return x, decoder_padding_mask + + def forward_copying_source(self, src_embeds, src_masks, tgt_masks): + length_sources = src_masks.sum(1) + length_targets = tgt_masks.sum(1) + mapped_inputs = _uniform_assignment(length_sources, length_targets).masked_fill( + ~tgt_masks, 0 + ) + copied_embedding = torch.gather( + src_embeds, + 1, + mapped_inputs.unsqueeze(-1).expand( + *mapped_inputs.size(), src_embeds.size(-1) + ), + ) + return copied_embedding + + def forward_length_prediction(self, length_out, encoder_out, tgt_tokens=None): + enc_feats = encoder_out["encoder_out"][0] # T x B x C + if len(encoder_out["encoder_padding_mask"]) > 0: + src_masks = encoder_out["encoder_padding_mask"][0] # B x T + else: + src_masks = None + if self.pred_length_offset: + if src_masks is None: + src_lengs = enc_feats.new_ones(enc_feats.size(1)).fill_( + enc_feats.size(0) + ) + else: + src_lengs = (~src_masks).transpose(0, 1).type_as(enc_feats).sum(0) + src_lengs = src_lengs.long() + + if tgt_tokens is not None: + # obtain the length target + tgt_lengs = tgt_tokens.ne(self.padding_idx).sum(1).long() + if self.pred_length_offset: + length_tgt = tgt_lengs - src_lengs + 128 + else: + length_tgt = tgt_lengs + length_tgt = length_tgt.clamp(min=0, max=255) + + else: + # predict the length target (greedy for now) + # TODO: implementing length-beam + pred_lengs = length_out.max(-1)[1] + if self.pred_length_offset: + length_tgt = pred_lengs - 128 + src_lengs + else: + length_tgt = pred_lengs + + return length_tgt + + +@register_model_architecture( + "nonautoregressive_transformer", "nonautoregressive_transformer" +) +def base_architecture(args): + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", False) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.dropout = getattr(args, "dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", False) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.apply_bert_init = getattr(args, "apply_bert_init", False) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + # --- special arguments --- + args.sg_length_pred = getattr(args, "sg_length_pred", False) + args.pred_length_offset = getattr(args, "pred_length_offset", False) + args.length_loss_factor = getattr(args, "length_loss_factor", 0.1) + args.src_embedding_copy = getattr(args, "src_embedding_copy", False) + + +@register_model_architecture( + "nonautoregressive_transformer", "nonautoregressive_transformer_wmt_en_de" +) +def nonautoregressive_transformer_wmt_en_de(args): + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/roberta/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/__init__.py new file mode 100644 index 00000000..4cd723ae --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/__init__.py @@ -0,0 +1,11 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .hub_interface import * # noqa +from .model import * # noqa +from .enc_dec import * # noqa +from .model_camembert import * # noqa +from .model_gottbert import * # noqa +from .model_xlmr import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/roberta/alignment_utils.py b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/alignment_utils.py new file mode 100644 index 00000000..ccc7f74c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/alignment_utils.py @@ -0,0 +1,118 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections import Counter +from typing import List + +import torch + + +def align_bpe_to_words(roberta, bpe_tokens: torch.LongTensor, other_tokens: List[str]): + """ + Helper to align GPT-2 BPE to other tokenization formats (e.g., spaCy). + + Args: + roberta (RobertaHubInterface): RoBERTa instance + bpe_tokens (torch.LongTensor): GPT-2 BPE tokens of shape `(T_bpe)` + other_tokens (List[str]): other tokens of shape `(T_words)` + + Returns: + List[str]: mapping from *other_tokens* to corresponding *bpe_tokens*. + """ + assert bpe_tokens.dim() == 1 + assert bpe_tokens[0] == 0 + + def clean(text): + return text.strip() + + # remove whitespaces to simplify alignment + bpe_tokens = [roberta.task.source_dictionary.string([x]) for x in bpe_tokens] + bpe_tokens = [ + clean(roberta.bpe.decode(x) if x not in {"", ""} else x) for x in bpe_tokens + ] + other_tokens = [clean(str(o)) for o in other_tokens] + + # strip leading + bpe_tokens = bpe_tokens[1:] + assert "".join(bpe_tokens) == "".join(other_tokens) + + # create alignment from every word to a list of BPE tokens + alignment = [] + bpe_toks = filter(lambda item: item[1] != "", enumerate(bpe_tokens, start=1)) + j, bpe_tok = next(bpe_toks) + for other_tok in other_tokens: + bpe_indices = [] + while True: + if other_tok.startswith(bpe_tok): + bpe_indices.append(j) + other_tok = other_tok[len(bpe_tok) :] + try: + j, bpe_tok = next(bpe_toks) + except StopIteration: + j, bpe_tok = None, None + elif bpe_tok.startswith(other_tok): + # other_tok spans multiple BPE tokens + bpe_indices.append(j) + bpe_tok = bpe_tok[len(other_tok) :] + other_tok = "" + else: + raise Exception('Cannot align "{}" and "{}"'.format(other_tok, bpe_tok)) + if other_tok == "": + break + assert len(bpe_indices) > 0 + alignment.append(bpe_indices) + assert len(alignment) == len(other_tokens) + + return alignment + + +def align_features_to_words(roberta, features, alignment): + """ + Align given features to words. + + Args: + roberta (RobertaHubInterface): RoBERTa instance + features (torch.Tensor): features to align of shape `(T_bpe x C)` + alignment: alignment between BPE tokens and words returned by + func:`align_bpe_to_words`. + """ + assert features.dim() == 2 + + bpe_counts = Counter(j for bpe_indices in alignment for j in bpe_indices) + assert bpe_counts[0] == 0 # shouldn't be aligned + denom = features.new([bpe_counts.get(j, 1) for j in range(len(features))]) + weighted_features = features / denom.unsqueeze(-1) + + output = [weighted_features[0]] + largest_j = -1 + for bpe_indices in alignment: + output.append(weighted_features[bpe_indices].sum(dim=0)) + largest_j = max(largest_j, *bpe_indices) + for j in range(largest_j + 1, len(features)): + output.append(weighted_features[j]) + output = torch.stack(output) + assert torch.all(torch.abs(output.sum(dim=0) - features.sum(dim=0)) < 1e-4) + return output + + +def spacy_nlp(): + if getattr(spacy_nlp, "_nlp", None) is None: + try: + from spacy.lang.en import English + + spacy_nlp._nlp = English() + except ImportError: + raise ImportError("Please install spacy with: pip install spacy") + return spacy_nlp._nlp + + +def spacy_tokenizer(): + if getattr(spacy_tokenizer, "_tokenizer", None) is None: + try: + nlp = spacy_nlp() + spacy_tokenizer._tokenizer = nlp.Defaults.create_tokenizer(nlp) + except ImportError: + raise ImportError("Please install spacy with: pip install spacy") + return spacy_tokenizer._tokenizer diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/roberta/enc_dec.py b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/enc_dec.py new file mode 100644 index 00000000..e538dee0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/enc_dec.py @@ -0,0 +1,192 @@ +import argparse +import logging + +import torch.nn as nn +import fairseq.checkpoint_utils +from fairseq.models import ( + FairseqEncoderDecoderModel, + register_model, + register_model_architecture, +) +from fairseq.models.transformer import TransformerDecoder +from fairseq.models.roberta import model as roberta + +logger = logging.getLogger(__name__) + + +@register_model("roberta_enc_dec") +class RobertaEncDecModel(FairseqEncoderDecoderModel): + @staticmethod + def add_args(parser): + parser.add_argument( + "--pretrained-mlm-checkpoint", + default=None, + type=str, + metavar="PRETRAINED", + help="path to pretrained mlm checkpoint", + ) + parser.add_argument( + "--pretrained-decoder", action="store_true", help="reload decoder" + ) + parser.add_argument( + "--hack-layernorm-embedding", + action="store_true", + help="hack to reload old models trained with encoder-normalize-before=False (no equivalent to encoder-normalize-before=False and layernorm_embedding=False", + ) + parser.add_argument( + "--share-decoder-input-output-embed", + action="store_true", + help="share decoder input and output embeddings", + ) + parser.add_argument( + "--share-all-embeddings", + action="store_true", + help="share encoder, decoder and output embeddings" + " (requires shared dictionary and embed dim)", + ) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present + base_enc_dec_architecture(args) + if args.pretrained_mlm_checkpoint: + arg_overrides = None + if args.hack_layernorm_embedding: + arg_overrides = {"layernorm_embedding": False} + loaded = fairseq.checkpoint_utils.load_model_ensemble_and_task( + [args.pretrained_mlm_checkpoint], arg_overrides=arg_overrides + ) + ([roberta_enc], _cfg, _task) = loaded + else: + # Do we need to edit untie_weights here ? + share_in_out = ( + args.share_decoder_input_output_embed or args.share_all_embeddings + ) + args.untie_weights_roberta = not share_in_out + if args.hack_layernorm_embedding: + args.layernorm_embedding = False + args.encoder_normalize_before = False + roberta_enc = roberta.RobertaModel.build_model(args, task) + + return cls.from_roberta(roberta_enc, args, task.source_dictionary) + + @staticmethod + def from_roberta(roberta_enc: roberta.RobertaModel, args, dictionary): + encoder = roberta_enc.encoder.sentence_encoder + vocab_size, embed_dim = encoder.embed_tokens.weight.shape + + if args.share_all_embeddings: + lm_head = roberta_enc.encoder.lm_head + assert encoder.embed_tokens.weight is lm_head.weight, ( + "Can't use --share-all-embeddings with a model " + "that was pretraiend with --untie-weights-roberta_enc" + ) + else: + lm_head = roberta.RobertaLMHead( + embed_dim, vocab_size, roberta_enc.args.activation_fn + ) + + dec_embs = nn.Embedding(vocab_size, embed_dim, dictionary.pad()) + if args.share_all_embeddings or args.share_decoder_input_output_embed: + # Note: I wasn't able to use Embedding _weight parameter to achive this sharing. + dec_embs.weight = lm_head.weight + + decoder = TransformerDecoder( + RobertaEncDecModel.read_args_from_roberta(roberta_enc.args), + dictionary, + dec_embs, + no_encoder_attn=False, + output_projection=lm_head, + ) + if getattr(args, "pretrained_decoder", False): + decoder_dict = encoder.state_dict() + + # TODO: hide setting "encoder_attn" layers behind a flag. + for k, w in list(decoder_dict.items()): + if ".self_attn" in k: + k_enc_attn = k.replace(".self_attn", ".encoder_attn") + decoder_dict[k_enc_attn] = w.detach().clone() + + for k, w in lm_head.state_dict().items(): + decoder_dict["output_projection." + k] = w + + missing_keys, unexpected_keys = decoder.load_state_dict( + decoder_dict, strict=False + ) + # missing_keys = [m for m in missing_keys if ".encoder_attn" not in m] + assert not missing_keys and not unexpected_keys, ( + "Failed to load state dict. " + f"Missing keys: {missing_keys}. " + f"Unexpected keys: {unexpected_keys}." + ) + + if args.share_all_embeddings: + assert decoder.output_projection.weight is decoder.embed_tokens.weight + assert encoder.embed_tokens.weight is decoder.embed_tokens.weight + elif args.share_decoder_input_output_embed: + assert decoder.output_projection.weight is decoder.embed_tokens.weight + assert encoder.embed_tokens.weight is not decoder.embed_tokens.weight + else: + assert decoder.output_projection.weight is not decoder.embed_tokens.weight + assert encoder.embed_tokens.weight is not decoder.embed_tokens.weight + + return RobertaEncDecModel(encoder, decoder) + + @staticmethod + def read_args_from_roberta(roberta_args: argparse.Namespace): + # TODO: this would become easier if encoder/decoder where using a similar + # TransformerConfig object + args = argparse.Namespace(**vars(roberta_args)) + attr_map = [ + ("encoder_attention_heads", "decoder_attention_heads"), + ("encoder_embed_dim", "decoder_embed_dim"), + ("encoder_embed_dim", "decoder_output_dim"), + ("encoder_normalize_before", "decoder_normalize_before"), + ("encoder_layers_to_keep", "decoder_layers_to_keep"), + ("encoder_ffn_embed_dim", "decoder_ffn_embed_dim"), + ("encoder_layerdrop", "decoder_layerdrop"), + ("encoder_layers", "decoder_layers"), + ("encoder_learned_pos", "decoder_learned_pos"), + # should this be set from here ? + ("max_positions", "max_target_positions"), + ] + for k1, k2 in attr_map: + setattr(args, k2, getattr(roberta_args, k1)) + + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = not roberta_args.untie_weights_roberta + return args + + def upgrade_state_dict_named(self, state_dict, name): + prefix = name + "." if name != "" else "" + super().upgrade_state_dict_named(state_dict, name) + old_keys = list(state_dict.keys()) + + # rename decoder -> encoder before upgrading children modules + for k in old_keys: + if k.startswith(prefix + "encoder.lm_head"): + state_dict.pop(k) + continue + new_k = k + new_k = new_k.replace(".sentence_encoder.", ".") + new_k = new_k.replace("decoder.lm_head.", "decoder.output_projection.") + if k == new_k: + continue + # print(k, "->", new_k) + state_dict[new_k] = state_dict.pop(k) + + +@register_model_architecture("roberta_enc_dec", "roberta_enc_dec") +def base_enc_dec_architecture(args): + args.hack_layernorm_embedding = getattr(args, "hack_layernorm_embedding", False) + args.pretrained_mlm_checkpoint = getattr(args, "pretrained_mlm_checkpoint", None) + args.pretrained_decoder = getattr(args, "pretrained_decoder", None) + args.share_all_embeddings = getattr(args, "share_all_embeddings", False) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + + roberta.base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/roberta/hub_interface.py b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/hub_interface.py new file mode 100644 index 00000000..ba298d63 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/hub_interface.py @@ -0,0 +1,235 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.data import encoders + + +class RobertaHubInterface(nn.Module): + """A simple PyTorch Hub interface to RoBERTa. + + Usage: https://github.com/pytorch/fairseq/tree/main/examples/roberta + """ + + def __init__(self, cfg, task, model): + super().__init__() + self.cfg = cfg + self.task = task + self.model = model + + self.bpe = encoders.build_bpe(cfg.bpe) + + # this is useful for determining the device + self.register_buffer("_float_tensor", torch.tensor([0], dtype=torch.float)) + + @property + def device(self): + return self._float_tensor.device + + def encode( + self, sentence: str, *addl_sentences, no_separator=False + ) -> torch.LongTensor: + """ + BPE-encode a sentence (or multiple sentences). + + Every sequence begins with a beginning-of-sentence (``) symbol. + Every sentence ends with an end-of-sentence (``) and we use an + extra end-of-sentence (``) as a separator. + + Example (single sentence): ` a b c ` + Example (sentence pair): ` d e f 1 2 3 ` + + The BPE encoding follows GPT-2. One subtle detail is that the GPT-2 BPE + requires leading spaces. For example:: + + >>> roberta.encode('Hello world').tolist() + [0, 31414, 232, 2] + >>> roberta.encode(' world').tolist() + [0, 232, 2] + >>> roberta.encode('world').tolist() + [0, 8331, 2] + """ + bpe_sentence = " " + self.bpe.encode(sentence) + " " + for s in addl_sentences: + bpe_sentence += " " if not no_separator else "" + bpe_sentence += " " + self.bpe.encode(s) + " " + tokens = self.task.source_dictionary.encode_line( + bpe_sentence, append_eos=False, add_if_not_exist=False + ) + return tokens.long() + + def decode(self, tokens: torch.LongTensor): + assert tokens.dim() == 1 + tokens = tokens.numpy() + if tokens[0] == self.task.source_dictionary.bos(): + tokens = tokens[1:] # remove + eos_mask = tokens == self.task.source_dictionary.eos() + doc_mask = eos_mask[1:] & eos_mask[:-1] + sentences = np.split(tokens, doc_mask.nonzero()[0] + 1) + sentences = [ + self.bpe.decode(self.task.source_dictionary.string(s)) for s in sentences + ] + if len(sentences) == 1: + return sentences[0] + return sentences + + def extract_features( + self, tokens: torch.LongTensor, return_all_hiddens: bool = False + ) -> torch.Tensor: + if tokens.dim() == 1: + tokens = tokens.unsqueeze(0) + if tokens.size(-1) > self.model.max_positions(): + raise ValueError( + "tokens exceeds maximum length: {} > {}".format( + tokens.size(-1), self.model.max_positions() + ) + ) + features, extra = self.model( + tokens.to(device=self.device), + features_only=True, + return_all_hiddens=return_all_hiddens, + ) + if return_all_hiddens: + # convert from T x B x C -> B x T x C + inner_states = extra["inner_states"] + return [inner_state.transpose(0, 1) for inner_state in inner_states] + else: + return features # just the last layer's features + + def register_classification_head( + self, name: str, num_classes: int = None, embedding_size: int = None, **kwargs + ): + self.model.register_classification_head( + name, num_classes=num_classes, embedding_size=embedding_size, **kwargs + ) + + def predict(self, head: str, tokens: torch.LongTensor, return_logits: bool = False): + features = self.extract_features(tokens.to(device=self.device)) + logits = self.model.classification_heads[head](features) + if return_logits: + return logits + return F.log_softmax(logits, dim=-1) + + def extract_features_aligned_to_words( + self, sentence: str, return_all_hiddens: bool = False + ) -> torch.Tensor: + """Extract RoBERTa features, aligned to spaCy's word-level tokenizer.""" + from fairseq.models.roberta import alignment_utils + from spacy.tokens import Doc + + nlp = alignment_utils.spacy_nlp() + tokenizer = alignment_utils.spacy_tokenizer() + + # tokenize both with GPT-2 BPE and spaCy + bpe_toks = self.encode(sentence) + spacy_toks = tokenizer(sentence) + spacy_toks_ws = [t.text_with_ws for t in tokenizer(sentence)] + alignment = alignment_utils.align_bpe_to_words(self, bpe_toks, spacy_toks_ws) + + # extract features and align them + features = self.extract_features( + bpe_toks, return_all_hiddens=return_all_hiddens + ) + features = features.squeeze(0) + aligned_feats = alignment_utils.align_features_to_words( + self, features, alignment + ) + + # wrap in spaCy Doc + doc = Doc( + nlp.vocab, + words=[""] + [x.text for x in spacy_toks] + [""], + spaces=[True] + + [x.endswith(" ") for x in spacy_toks_ws[:-1]] + + [True, False], + ) + assert len(doc) == aligned_feats.size(0) + doc.user_token_hooks["vector"] = lambda token: aligned_feats[token.i] + return doc + + def fill_mask(self, masked_input: str, topk: int = 5): + masked_token = "" + assert ( + masked_token in masked_input and masked_input.count(masked_token) == 1 + ), "Please add one {0} token for the input, eg: 'He is a {0} guy'".format( + masked_token + ) + + text_spans = masked_input.split(masked_token) + text_spans_bpe = ( + (" {0} ".format(masked_token)) + .join([self.bpe.encode(text_span.rstrip()) for text_span in text_spans]) + .strip() + ) + tokens = self.task.source_dictionary.encode_line( + " " + text_spans_bpe + " ", + append_eos=False, + add_if_not_exist=False, + ) + + masked_index = (tokens == self.task.mask_idx).nonzero(as_tuple=False) + if tokens.dim() == 1: + tokens = tokens.unsqueeze(0) + + with utils.model_eval(self.model): + features, extra = self.model( + tokens.long().to(device=self.device), + features_only=False, + return_all_hiddens=False, + ) + logits = features[0, masked_index, :].squeeze() + prob = logits.softmax(dim=0) + values, index = prob.topk(k=topk, dim=0) + topk_predicted_token_bpe = self.task.source_dictionary.string(index) + + topk_filled_outputs = [] + for index, predicted_token_bpe in enumerate( + topk_predicted_token_bpe.split(" ") + ): + predicted_token = self.bpe.decode(predicted_token_bpe) + # Quick hack to fix https://github.com/pytorch/fairseq/issues/1306 + if predicted_token_bpe.startswith("\u2581"): + predicted_token = " " + predicted_token + if " {0}".format(masked_token) in masked_input: + topk_filled_outputs.append( + ( + masked_input.replace( + " {0}".format(masked_token), predicted_token + ), + values[index].item(), + predicted_token, + ) + ) + else: + topk_filled_outputs.append( + ( + masked_input.replace(masked_token, predicted_token), + values[index].item(), + predicted_token, + ) + ) + return topk_filled_outputs + + def disambiguate_pronoun(self, sentence: str) -> bool: + """ + Usage:: + + >>> disambiguate_pronoun('The _trophy_ would not fit in the brown suitcase because [it] was too big.') + True + + >>> disambiguate_pronoun('The trophy would not fit in the brown suitcase because [it] was too big.') + 'The trophy' + """ + assert hasattr( + self.task, "disambiguate_pronoun" + ), "roberta.disambiguate_pronoun() requires a model trained with the WSC task." + with utils.model_eval(self.model): + return self.task.disambiguate_pronoun( + self.model, sentence, use_cuda=self.device.type == "cuda" + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model.py b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model.py new file mode 100644 index 00000000..d7ced919 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model.py @@ -0,0 +1,700 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +RoBERTa: A Robustly Optimized BERT Pretraining Approach. +""" + +import logging + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from fairseq import utils +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderModel, + register_model, + register_model_architecture, +) +from fairseq.models.transformer import DEFAULT_MIN_PARAMS_TO_WRAP, TransformerEncoder +from fairseq.modules import LayerNorm +from fairseq.modules.quant_noise import quant_noise as apply_quant_noise_ +from fairseq.modules.transformer_sentence_encoder import init_bert_params +from fairseq.utils import safe_getattr, safe_hasattr + +from .hub_interface import RobertaHubInterface + +logger = logging.getLogger(__name__) + + +@register_model("roberta") +class RobertaModel(FairseqEncoderModel): + @classmethod + def hub_models(cls): + return { + "roberta.base": "http://dl.fbaipublicfiles.com/fairseq/models/roberta.base.tar.gz", + "roberta.large": "http://dl.fbaipublicfiles.com/fairseq/models/roberta.large.tar.gz", + "roberta.large.mnli": "http://dl.fbaipublicfiles.com/fairseq/models/roberta.large.mnli.tar.gz", + "roberta.large.wsc": "http://dl.fbaipublicfiles.com/fairseq/models/roberta.large.wsc.tar.gz", + } + + def __init__(self, args, encoder): + super().__init__(encoder) + self.args = args + + # We follow BERT's random weight initialization + self.apply(init_bert_params) + + self.classification_heads = nn.ModuleDict() + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + parser.add_argument( + "--encoder-layers", type=int, metavar="L", help="num encoder layers" + ) + parser.add_argument( + "--encoder-embed-dim", + type=int, + metavar="H", + help="encoder embedding dimension", + ) + parser.add_argument( + "--encoder-ffn-embed-dim", + type=int, + metavar="F", + help="encoder embedding dimension for FFN", + ) + parser.add_argument( + "--encoder-attention-heads", + type=int, + metavar="A", + help="num encoder attention heads", + ) + parser.add_argument( + "--activation-fn", + choices=utils.get_available_activation_fns(), + help="activation function to use", + ) + parser.add_argument( + "--pooler-activation-fn", + choices=utils.get_available_activation_fns(), + help="activation function to use for pooler layer", + ) + parser.add_argument( + "--encoder-normalize-before", + action="store_true", + help="apply layernorm before each encoder block", + ) + parser.add_argument( + "--layernorm-embedding", + action="store_true", + help="add layernorm to embedding", + ) + parser.add_argument( + "--dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--attention-dropout", + type=float, + metavar="D", + help="dropout probability for attention weights", + ) + parser.add_argument( + "--activation-dropout", + type=float, + metavar="D", + help="dropout probability after activation in FFN", + ) + parser.add_argument( + "--pooler-dropout", + type=float, + metavar="D", + help="dropout probability in the masked_lm pooler layers", + ) + parser.add_argument( + "--max-positions", type=int, help="number of positional embeddings to learn" + ) + parser.add_argument( + "--load-checkpoint-heads", + action="store_true", + help="(re-)register and load heads when loading checkpoints", + ) + parser.add_argument( + "--untie-weights-roberta", + action="store_true", + help="Untie weights between embeddings and classifiers in RoBERTa", + ) + # args for "Reducing Transformer Depth on Demand with Structured Dropout" (Fan et al., 2019) + parser.add_argument( + "--encoder-layerdrop", + type=float, + metavar="D", + default=0, + help="LayerDrop probability for encoder", + ) + parser.add_argument( + "--encoder-layers-to-keep", + default=None, + help="which layers to *keep* when pruning as a comma-separated list", + ) + # args for Training with Quantization Noise for Extreme Model Compression ({Fan*, Stock*} et al., 2020) + parser.add_argument( + "--quant-noise-pq", + type=float, + metavar="D", + default=0, + help="iterative PQ quantization noise at training time", + ) + parser.add_argument( + "--quant-noise-pq-block-size", + type=int, + metavar="D", + default=8, + help="block size of quantization noise at training time", + ) + parser.add_argument( + "--quant-noise-scalar", + type=float, + metavar="D", + default=0, + help="scalar quantization noise and scalar quantization at training time", + ) + # args for "Better Fine-Tuning by Reducing Representational Collapse" (Aghajanyan et al. 2020) + parser.add_argument( + "--spectral-norm-classification-head", + action="store_true", + default=False, + help="Apply spectral normalization on the classification head", + ) + # args for Fully Sharded Data Parallel (FSDP) training + parser.add_argument( + "--min-params-to-wrap", + type=int, + metavar="D", + default=DEFAULT_MIN_PARAMS_TO_WRAP, + help=( + "minimum number of params for a layer to be wrapped with FSDP() when " + "training with --ddp-backend=fully_sharded. Smaller values will " + "improve memory efficiency, but may make torch.distributed " + "communication less efficient due to smaller input sizes. This option " + "is set to 0 (i.e., always wrap) when --checkpoint-activations or " + "--offload-activations are passed." + ), + ) + # args for AdaPruning + # In short, it adds regularizarion for the multihead attention module and feed forward neural nets + # For more details, please refer to the paper https://openreview.net/forum?id=_CMSV7FTzGI + parser.add_argument( + "--mha-reg-scale-factor", + type=float, + metavar="D", + default=0.0, + help="scaling factor for regularization term in adptive pruning, recommendation is 0.000375", + ) + parser.add_argument( + "--ffn-reg-scale-factor", + type=float, + metavar="D", + default=0.0, + help="scaling factor for regularization term in adptive pruning, recommendation is 0.000375", + ) + parser.add_argument( + "--mha-heads-to-keep", + type=int, + metavar="D", + default=-1, + help="number of heads to keep in each multi-head attention module, -1 means keeping all heads", + ) + parser.add_argument( + "--ffn-blocks-to-remove", + type=int, + metavar="D", + default=-1, + help="number of feedforward blocks to remove in each transformer layer, -1 means keeping all ffn blocks", + ) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + from omegaconf import OmegaConf + + if OmegaConf.is_config(args): + OmegaConf.set_struct(args, False) + + # make sure all arguments are present + base_architecture(args) + + if not safe_hasattr(args, "max_positions"): + if not safe_hasattr(args, "tokens_per_sample"): + args.tokens_per_sample = task.max_positions() + args.max_positions = args.tokens_per_sample + + encoder = RobertaEncoder(args, task.source_dictionary) + + if OmegaConf.is_config(args): + OmegaConf.set_struct(args, True) + + return cls(args, encoder) + + def forward( + self, + src_tokens, + features_only=False, + return_all_hiddens=False, + classification_head_name=None, + **kwargs, + ): + if classification_head_name is not None: + features_only = True + + x, extra = self.encoder(src_tokens, features_only, return_all_hiddens, **kwargs) + + if classification_head_name is not None: + x = self.classification_heads[classification_head_name](x) + return x, extra + + def _get_adaptive_head_loss(self): + norm_loss = 0 + scaling = float(self.args.mha_reg_scale_factor) + for layer in self.encoder.sentence_encoder.layers: + norm_loss_layer = 0 + for i in range(layer.self_attn.num_heads): + start_idx = i * layer.self_attn.head_dim + end_idx = (i + 1) * layer.self_attn.head_dim + norm_loss_layer += scaling * ( + torch.sum( + torch.abs( + layer.self_attn.q_proj.weight[ + start_idx:end_idx, + ] + ) + ) + + torch.sum( + torch.abs(layer.self_attn.q_proj.bias[start_idx:end_idx]) + ) + ) + norm_loss_layer += scaling * ( + torch.sum( + torch.abs( + layer.self_attn.k_proj.weight[ + start_idx:end_idx, + ] + ) + ) + + torch.sum( + torch.abs(layer.self_attn.k_proj.bias[start_idx:end_idx]) + ) + ) + norm_loss_layer += scaling * ( + torch.sum( + torch.abs( + layer.self_attn.v_proj.weight[ + start_idx:end_idx, + ] + ) + ) + + torch.sum( + torch.abs(layer.self_attn.v_proj.bias[start_idx:end_idx]) + ) + ) + + norm_loss += norm_loss_layer + return norm_loss + + def _get_adaptive_ffn_loss(self): + ffn_scale_factor = float(self.args.ffn_reg_scale_factor) + filter_loss = 0 + for layer in self.encoder.sentence_encoder.layers: + filter_loss += torch.sum( + torch.abs(layer.fc1.weight * ffn_scale_factor) + ) + torch.sum(torch.abs(layer.fc2.weight * ffn_scale_factor)) + filter_loss += torch.sum( + torch.abs(layer.fc1.bias * ffn_scale_factor) + ) + torch.sum(torch.abs(layer.fc2.bias * ffn_scale_factor)) + return filter_loss + + def get_normalized_probs(self, net_output, log_probs, sample=None): + """Get normalized probabilities (or log probs) from a net's output.""" + logits = net_output[0].float() + if log_probs: + return F.log_softmax(logits, dim=-1) + else: + return F.softmax(logits, dim=-1) + + def register_classification_head( + self, name, num_classes=None, inner_dim=None, **kwargs + ): + """Register a classification head.""" + if name in self.classification_heads: + prev_num_classes = self.classification_heads[name].out_proj.out_features + prev_inner_dim = self.classification_heads[name].dense.out_features + if num_classes != prev_num_classes or inner_dim != prev_inner_dim: + logger.warning( + 're-registering head "{}" with num_classes {} (prev: {}) ' + "and inner_dim {} (prev: {})".format( + name, num_classes, prev_num_classes, inner_dim, prev_inner_dim + ) + ) + self.classification_heads[name] = RobertaClassificationHead( + input_dim=self.args.encoder_embed_dim, + inner_dim=inner_dim or self.args.encoder_embed_dim, + num_classes=num_classes, + activation_fn=self.args.pooler_activation_fn, + pooler_dropout=self.args.pooler_dropout, + q_noise=self.args.quant_noise_pq, + qn_block_size=self.args.quant_noise_pq_block_size, + do_spectral_norm=self.args.spectral_norm_classification_head, + ) + + @property + def supported_targets(self): + return {"self"} + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + bpe="gpt2", + **kwargs, + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + bpe=bpe, + load_checkpoint_heads=True, + **kwargs, + ) + + logger.info(x["args"]) + return RobertaHubInterface(x["args"], x["task"], x["models"][0]) + + def upgrade_state_dict_named(self, state_dict, name): + prefix = name + "." if name != "" else "" + + # rename decoder -> encoder before upgrading children modules + for k in list(state_dict.keys()): + if k.startswith(prefix + "decoder"): + new_k = prefix + "encoder" + k[len(prefix + "decoder") :] + state_dict[new_k] = state_dict[k] + del state_dict[k] + + # rename emb_layer_norm -> layernorm_embedding + for k in list(state_dict.keys()): + if ".emb_layer_norm." in k: + new_k = k.replace(".emb_layer_norm.", ".layernorm_embedding.") + state_dict[new_k] = state_dict[k] + del state_dict[k] + + # upgrade children modules + super().upgrade_state_dict_named(state_dict, name) + + # Handle new classification heads present in the state dict. + current_head_names = ( + [] + if not hasattr(self, "classification_heads") + else self.classification_heads.keys() + ) + keys_to_delete = [] + for k in state_dict.keys(): + if not k.startswith(prefix + "classification_heads."): + continue + + head_name = k[len(prefix + "classification_heads.") :].split(".")[0] + num_classes = state_dict[ + prefix + "classification_heads." + head_name + ".out_proj.weight" + ].size(0) + inner_dim = state_dict[ + prefix + "classification_heads." + head_name + ".dense.weight" + ].size(0) + + if getattr(self.args, "load_checkpoint_heads", False): + if head_name not in current_head_names: + self.register_classification_head(head_name, num_classes, inner_dim) + else: + if head_name not in current_head_names: + logger.warning( + "deleting classification head ({}) from checkpoint " + "not present in current model: {}".format(head_name, k) + ) + keys_to_delete.append(k) + elif ( + num_classes + != self.classification_heads[head_name].out_proj.out_features + or inner_dim + != self.classification_heads[head_name].dense.out_features + ): + logger.warning( + "deleting classification head ({}) from checkpoint " + "with different dimensions than current model: {}".format( + head_name, k + ) + ) + keys_to_delete.append(k) + for k in keys_to_delete: + del state_dict[k] + + # Copy any newly-added classification heads into the state dict + # with their current weights. + if hasattr(self, "classification_heads"): + cur_state = self.classification_heads.state_dict() + for k, v in cur_state.items(): + if prefix + "classification_heads." + k not in state_dict: + logger.info("Overwriting " + prefix + "classification_heads." + k) + state_dict[prefix + "classification_heads." + k] = v + + # adapt data2vec models + if ( + "encoder._ema" in state_dict + and "encoder.lm_head.weight" not in state_dict + ): + lm_state = self.encoder.lm_head.state_dict() + for k, v in lm_state.items(): + state_dict["encoder.lm_head." + k] = v + + for k in list(state_dict.keys()): + if k.startswith("encoder.regression_head") or k == "encoder._ema": + del state_dict[k] + + +class RobertaLMHead(nn.Module): + """Head for masked language modeling.""" + + def __init__(self, embed_dim, output_dim, activation_fn, weight=None): + super().__init__() + self.dense = nn.Linear(embed_dim, embed_dim) + self.activation_fn = utils.get_activation_fn(activation_fn) + self.layer_norm = LayerNorm(embed_dim) + + if weight is None: + weight = nn.Linear(embed_dim, output_dim, bias=False).weight + self.weight = weight + self.bias = nn.Parameter(torch.zeros(output_dim)) + + def forward(self, features, masked_tokens=None, **kwargs): + # Only project the masked tokens while training, + # saves both memory and computation + if masked_tokens is not None: + features = features[masked_tokens, :] + + x = self.dense(features) + x = self.activation_fn(x) + x = self.layer_norm(x) + # project back to size of vocabulary with bias + x = F.linear(x, self.weight) + self.bias + return x + + +class RobertaClassificationHead(nn.Module): + """Head for sentence-level classification tasks.""" + + def __init__( + self, + input_dim, + inner_dim, + num_classes, + activation_fn, + pooler_dropout, + q_noise=0, + qn_block_size=8, + do_spectral_norm=False, + ): + super().__init__() + self.dense = nn.Linear(input_dim, inner_dim) + self.activation_fn = utils.get_activation_fn(activation_fn) + self.dropout = nn.Dropout(p=pooler_dropout) + self.out_proj = apply_quant_noise_( + nn.Linear(inner_dim, num_classes), q_noise, qn_block_size + ) + if do_spectral_norm: + if q_noise != 0: + raise NotImplementedError( + "Attempting to use Spectral Normalization with Quant Noise. This is not officially supported" + ) + self.out_proj = torch.nn.utils.spectral_norm(self.out_proj) + + def forward(self, features, **kwargs): + x = features[:, 0, :] # take token (equiv. to [CLS]) + x = self.dropout(x) + x = self.dense(x) + x = self.activation_fn(x) + x = self.dropout(x) + x = self.out_proj(x) + return x + + +class RobertaEncoder(FairseqEncoder): + """RoBERTa encoder.""" + + def __init__(self, args, dictionary): + super().__init__(dictionary) + + # set any missing default values + base_architecture(args) + self.args = args + + if args.encoder_layers_to_keep: + args.encoder_layers = len(args.encoder_layers_to_keep.split(",")) + + embed_tokens = self.build_embedding( + len(dictionary), args.encoder_embed_dim, dictionary.pad() + ) + + self.sentence_encoder = self.build_encoder(args, dictionary, embed_tokens) + + self.lm_head = self.build_lm_head( + embed_dim=args.encoder_embed_dim, + output_dim=len(dictionary), + activation_fn=args.activation_fn, + weight=( + self.sentence_encoder.embed_tokens.weight + if not args.untie_weights_roberta + else None + ), + ) + + def build_embedding(self, vocab_size, embedding_dim, padding_idx): + return nn.Embedding(vocab_size, embedding_dim, padding_idx) + + def build_encoder(self, args, dictionary, embed_tokens): + encoder = TransformerEncoder(args, dictionary, embed_tokens) + encoder.apply(init_bert_params) + return encoder + + def build_lm_head(self, embed_dim, output_dim, activation_fn, weight): + return RobertaLMHead(embed_dim, output_dim, activation_fn, weight) + + def forward( + self, + src_tokens, + features_only=False, + return_all_hiddens=False, + masked_tokens=None, + **unused, + ): + """ + Args: + src_tokens (LongTensor): input tokens of shape `(batch, src_len)` + features_only (bool, optional): skip LM head and just return + features. If True, the output will be of shape + `(batch, src_len, embed_dim)`. + return_all_hiddens (bool, optional): also return all of the + intermediate hidden states (default: False). + + Returns: + tuple: + - the LM output of shape `(batch, src_len, vocab)` + - a dictionary of additional data, where 'inner_states' + is a list of hidden states. Note that the hidden + states have shape `(src_len, batch, vocab)`. + """ + x, extra = self.extract_features( + src_tokens, return_all_hiddens=return_all_hiddens + ) + if not features_only: + x = self.output_layer(x, masked_tokens=masked_tokens) + return x, extra + + def extract_features(self, src_tokens, return_all_hiddens=False, **kwargs): + encoder_out = self.sentence_encoder( + src_tokens, + return_all_hiddens=return_all_hiddens, + token_embeddings=kwargs.get("token_embeddings", None), + ) + # T x B x C -> B x T x C + features = encoder_out["encoder_out"][0].transpose(0, 1) + inner_states = encoder_out["encoder_states"] if return_all_hiddens else None + return features, {"inner_states": inner_states} + + def output_layer(self, features, masked_tokens=None, **unused): + return self.lm_head(features, masked_tokens) + + def max_positions(self): + """Maximum output length supported by the encoder.""" + return self.args.max_positions + + +@register_model_architecture("roberta", "roberta") +def base_architecture(args): + args.encoder_layers = safe_getattr(args, "encoder_layers", 12) + args.encoder_embed_dim = safe_getattr(args, "encoder_embed_dim", 768) + args.encoder_ffn_embed_dim = safe_getattr(args, "encoder_ffn_embed_dim", 3072) + args.encoder_attention_heads = safe_getattr(args, "encoder_attention_heads", 12) + + args.dropout = safe_getattr(args, "dropout", 0.1) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.1) + args.activation_dropout = safe_getattr(args, "activation_dropout", 0.0) + args.pooler_dropout = safe_getattr(args, "pooler_dropout", 0.0) + + args.max_source_positions = safe_getattr(args, "max_positions", 512) + args.no_token_positional_embeddings = safe_getattr( + args, "no_token_positional_embeddings", False + ) + + # BERT has a few structural differences compared to the original Transformer + args.encoder_learned_pos = safe_getattr(args, "encoder_learned_pos", True) + args.layernorm_embedding = safe_getattr(args, "layernorm_embedding", True) + args.no_scale_embedding = safe_getattr(args, "no_scale_embedding", True) + args.activation_fn = safe_getattr(args, "activation_fn", "gelu") + args.encoder_normalize_before = safe_getattr( + args, "encoder_normalize_before", False + ) + args.pooler_activation_fn = safe_getattr(args, "pooler_activation_fn", "tanh") + args.untie_weights_roberta = safe_getattr(args, "untie_weights_roberta", False) + + # Adaptive input config + args.adaptive_input = safe_getattr(args, "adaptive_input", False) + + # LayerDrop config + args.encoder_layerdrop = safe_getattr(args, "encoder_layerdrop", 0.0) + args.encoder_layers_to_keep = safe_getattr(args, "encoder_layers_to_keep", None) + + # Quantization noise config + args.quant_noise_pq = safe_getattr(args, "quant_noise_pq", 0) + args.quant_noise_pq_block_size = safe_getattr(args, "quant_noise_pq_block_size", 8) + args.quant_noise_scalar = safe_getattr(args, "quant_noise_scalar", 0) + + # R4F config + args.spectral_norm_classification_head = safe_getattr( + args, "spectral_norm_classification_head", False + ) + + +@register_model_architecture("roberta", "roberta_prenorm") +def roberta_prenorm_architecture(args): + args.layernorm_embedding = safe_getattr(args, "layernorm_embedding", False) + args.encoder_normalize_before = safe_getattr(args, "encoder_normalize_before", True) + base_architecture(args) + + +@register_model_architecture("roberta", "roberta_base") +def roberta_base_architecture(args): + base_architecture(args) + + +@register_model_architecture("roberta", "roberta_large") +def roberta_large_architecture(args): + args.encoder_layers = safe_getattr(args, "encoder_layers", 24) + args.encoder_embed_dim = safe_getattr(args, "encoder_embed_dim", 1024) + args.encoder_ffn_embed_dim = safe_getattr(args, "encoder_ffn_embed_dim", 4096) + args.encoder_attention_heads = safe_getattr(args, "encoder_attention_heads", 16) + base_architecture(args) + + +@register_model_architecture("roberta", "xlm") +def xlm_architecture(args): + args.encoder_layers = safe_getattr(args, "encoder_layers", 16) + args.encoder_embed_dim = safe_getattr(args, "encoder_embed_dim", 1280) + args.encoder_ffn_embed_dim = safe_getattr(args, "encoder_ffn_embed_dim", 1280 * 4) + args.encoder_attention_heads = safe_getattr(args, "encoder_attention_heads", 16) + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_camembert.py b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_camembert.py new file mode 100644 index 00000000..46447546 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_camembert.py @@ -0,0 +1,50 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +CamemBERT: a Tasty French Language Model +""" + +from fairseq.models import register_model + +from .hub_interface import RobertaHubInterface +from .model import RobertaModel + + +@register_model("camembert") +class CamembertModel(RobertaModel): + @classmethod + def hub_models(cls): + return { + "camembert": "http://dl.fbaipublicfiles.com/fairseq/models/camembert-base.tar.gz", + "camembert.v0": "http://dl.fbaipublicfiles.com/fairseq/models/camembert-base.tar.gz", + "camembert-base": "http://dl.fbaipublicfiles.com/fairseq/models/camembert-base.tar.gz", + "camembert-large": "http://dl.fbaipublicfiles.com/fairseq/models/camembert-large.tar.gz", + "camembert-base-ccnet": "http://dl.fbaipublicfiles.com/fairseq/models/camembert-base-ccnet.tar.gz", + "camembert-base-ccnet-4gb": "http://dl.fbaipublicfiles.com/fairseq/models/camembert-base-ccnet-4gb.tar.gz", + "camembert-base-wikipedia-4gb": "http://dl.fbaipublicfiles.com/fairseq/models/camembert-base-wikipedia-4gb.tar.gz", + "camembert-base-oscar-4gb": "http://dl.fbaipublicfiles.com/fairseq/models/camembert-base-oscar-4gb.tar.gz", + } + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + bpe="sentencepiece", + **kwargs + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + bpe=bpe, + load_checkpoint_heads=True, + **kwargs, + ) + return RobertaHubInterface(x["args"], x["task"], x["models"][0]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_gottbert.py b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_gottbert.py new file mode 100644 index 00000000..dc7a019b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_gottbert.py @@ -0,0 +1,49 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +GottBERT: a pure German Language Model +""" + +from fairseq.models import register_model + +from .hub_interface import RobertaHubInterface +from .model import RobertaModel + + +@register_model("gottbert") +class GottbertModel(RobertaModel): + @classmethod + def hub_models(cls): + return { + "gottbert-base": "https://dl.gottbert.de/fairseq/models/gottbert-base.tar.gz", + } + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + bpe="hf_byte_bpe", + bpe_vocab="vocab.json", + bpe_merges="merges.txt", + bpe_add_prefix_space=False, + **kwargs + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + bpe=bpe, + load_checkpoint_heads=True, + bpe_vocab=bpe_vocab, + bpe_merges=bpe_merges, + bpe_add_prefix_space=bpe_add_prefix_space, + **kwargs, + ) + return RobertaHubInterface(x["args"], x["task"], x["models"][0]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_xlmr.py b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_xlmr.py new file mode 100644 index 00000000..cf6e354d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/roberta/model_xlmr.py @@ -0,0 +1,46 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Unsupervised Cross-lingual Representation Learning at Scale +""" + +from fairseq.models import register_model + +from .hub_interface import RobertaHubInterface +from .model import RobertaModel + + +@register_model("xlmr") +class XLMRModel(RobertaModel): + @classmethod + def hub_models(cls): + return { + "xlmr.base": "http://dl.fbaipublicfiles.com/fairseq/models/xlmr.base.tar.gz", + "xlmr.large": "http://dl.fbaipublicfiles.com/fairseq/models/xlmr.large.tar.gz", + "xlmr.xl": "http://dl.fbaipublicfiles.com/fairseq/models/xlmr/xlmr.xl.tar.gz", + "xlmr.xxl": "http://dl.fbaipublicfiles.com/fairseq/models/xlmr/xlmr.xxl.tar.gz", + } + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + bpe="sentencepiece", + **kwargs + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + bpe=bpe, + load_checkpoint_heads=True, + **kwargs, + ) + return RobertaHubInterface(x["args"], x["task"], x["models"][0]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/__init__.py new file mode 100644 index 00000000..41be5e75 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/__init__.py @@ -0,0 +1,8 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .modules import * # noqa +from .s2s_transformer import * # noqa +from .s2s_conformer import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/modules.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/modules.py new file mode 100644 index 00000000..a2049816 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/modules.py @@ -0,0 +1,59 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from torch import nn + +from fairseq.models import FairseqEncoder +from fairseq.models.transformer import Linear + + +class CTCDecoder(FairseqEncoder): + def __init__(self, dictionary, in_dim): + super().__init__(dictionary) + self.proj = nn.Linear(in_dim, len(dictionary)) + + def forward(self, src_tokens, src_lengths=None, **kwargs): + encoder_out = self.proj(src_tokens) + return {"encoder_out": encoder_out} + + +class StackedEmbedding(nn.Embedding): + """Embedding module that supports stacked units -> single embedding""" + + def __init__(self, num_embeddings, embed_dim, padding_idx, num_stacked=1): + super().__init__(num_embeddings, embed_dim, padding_idx) + # follow transformer.Embedding + nn.init.normal_(self.weight, mean=0, std=embed_dim**-0.5) + nn.init.constant_(self.weight[padding_idx], 0) + + self.offset = ( + 4 # skip , , , , specific to fairseq dictionary + ) + self.vocab_size = num_embeddings - self.offset + self.num_stacked = num_stacked + + if self.num_stacked > 1: + self.project_in_dim = Linear(embed_dim * num_stacked, embed_dim, bias=False) + + def forward(self, input): + if self.num_stacked == 1: + return super().forward(input) + + # expand input indices + mask = input >= self.offset + stacked_input = [] + cum_input = input.new_zeros(input.shape) + for i in range(1, self.num_stacked + 1): + div = pow(self.vocab_size, i) + next_input = torch.remainder(input - self.offset - cum_input, div) + cum_input += next_input + next_input = torch.floor_divide(next_input, div // self.vocab_size) + stacked_input.append((next_input + self.offset) * mask + input * ~mask) + + stacked_input = torch.stack(stacked_input[::-1], dim=2) + embed = super().forward(stacked_input).view(input.size(0), input.size(1), -1) + embed = self.project_in_dim(embed) + return embed diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/s2s_conformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/s2s_conformer.py new file mode 100644 index 00000000..a232412c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/s2s_conformer.py @@ -0,0 +1,111 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from pathlib import Path +import torch + +from fairseq import checkpoint_utils +from fairseq.models import ( + register_model, + register_model_architecture, +) +from fairseq.data.audio.data_cfg import S2SDataConfig +from fairseq.models.speech_to_text import S2TConformerEncoder +from fairseq.models.speech_to_speech import ( + S2UTTransformerModel, + s2ut_architecture_base as s2ut_transformer_architecture_base, +) +from fairseq.models.transformer import ( + Linear, +) + + +logger = logging.getLogger(__name__) + + +class S2SConformerEncoder(S2TConformerEncoder): + """Based on S2T transformer encoder, with support + to incorporate target speaker embedding.""" + + def __init__(self, args): + super().__init__(args) + + self.spk_emb_proj = None + if args.target_speaker_embed: + self.spk_emb_proj = Linear( + args.encoder_embed_dim + args.speaker_embed_dim, args.encoder_embed_dim + ) + + def forward( + self, src_tokens, src_lengths, tgt_speaker=None, return_all_hiddens=False + ): + out = super().forward(src_tokens, src_lengths, return_all_hiddens) + + if self.spk_emb_proj: + x = out["encoder_out"][0] + seq_len, bsz, _ = x.size() + tgt_speaker_emb = tgt_speaker.view(1, bsz, -1).expand(seq_len, bsz, -1) + x = self.spk_emb_proj(torch.cat([x, tgt_speaker_emb], dim=2)) + out["encoder_out"][0] = x + + return out + + +@register_model("s2ut_conformer") +class S2UTConformerModel(S2UTTransformerModel): + """ + Direct speech-to-speech translation model with S2T Conformer encoder + Transformer discrete unit decoder + """ + + @staticmethod + def add_args(parser): + S2UTTransformerModel.add_args(parser) + parser.add_argument("--depthwise-conv-kernel-size", default=31) + parser.add_argument( + "--attn-type", + default=None, + help="If not specified uses fairseq MHA. Other valid option is espnet for using conformer", + ) + parser.add_argument( + "--pos-enc-type", + default="abs", + help="Must be specified in addition to attn-type=espnet for rel_pos and rope", + ) + + @classmethod + def build_encoder(cls, args): + print(args) + data_cfg = S2SDataConfig(Path(args.data) / args.config_yaml) + args.input_feat_per_channel = data_cfg.input_feat_per_channel + args.input_channels = data_cfg.input_transformed_channels + + encoder = S2SConformerEncoder(args) + pretraining_path = getattr(args, "load_pretrained_encoder_from", None) + if pretraining_path is not None: + if not Path(pretraining_path).exists(): + logger.warning( + f"skipped pretraining because {pretraining_path} does not exist" + ) + else: + encoder = checkpoint_utils.load_pretrained_component_from_model( + component=encoder, checkpoint=pretraining_path + ) + logger.info(f"loaded pretrained encoder from: {pretraining_path}") + return encoder + + +@register_model_architecture("s2ut_conformer", "s2ut_conformer") +def s2ut_base_architecture(args): + args.attn_type = getattr(args, "attn_type", None) + args.pos_enc_type = getattr(args, "pos_enc_type", "abs") + args.max_source_positions = getattr(args, "max_source_positions", 6000) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.dropout = getattr(args, "dropout", 0.1) + args.encoder_layers = getattr(args, "encoder_layers", 16) + args.depthwise_conv_kernel_size = getattr(args, "depthwise_conv_kernel_size", 31) + s2ut_transformer_architecture_base(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/s2s_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/s2s_transformer.py new file mode 100644 index 00000000..a5954a83 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_speech/s2s_transformer.py @@ -0,0 +1,703 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from pathlib import Path +from typing import Any, Dict, List, Optional + +import torch +from torch import Tensor + +from fairseq import checkpoint_utils, utils +from fairseq.models import ( + FairseqEncoderModel, + FairseqEncoderDecoderModel, + FairseqLanguageModel, + register_model, + register_model_architecture, +) +from fairseq.models.speech_to_text import S2TTransformerEncoder +from fairseq.models.speech_to_speech.modules import CTCDecoder, StackedEmbedding +from fairseq.models.text_to_speech import TTSTransformerDecoder +from fairseq.models.transformer import ( + Linear, + TransformerDecoder, + TransformerModelBase, +) + + +logger = logging.getLogger(__name__) + + +class S2STransformerEncoder(S2TTransformerEncoder): + """Based on S2T transformer encoder, with support + to incorporate target speaker embedding.""" + + def __init__(self, args): + super().__init__(args) + + self.spk_emb_proj = None + if args.target_speaker_embed: + self.spk_emb_proj = Linear( + args.encoder_embed_dim + args.speaker_embed_dim, args.encoder_embed_dim + ) + + def forward( + self, src_tokens, src_lengths, tgt_speaker=None, return_all_hiddens=False + ): + out = super().forward(src_tokens, src_lengths, return_all_hiddens) + + if self.spk_emb_proj: + x = out["encoder_out"][0] + seq_len, bsz, _ = x.size() + tgt_speaker_emb = tgt_speaker.view(1, bsz, -1).expand(seq_len, bsz, -1) + x = self.spk_emb_proj(torch.cat([x, tgt_speaker_emb], dim=2)) + out["encoder_out"][0] = x + + return out + + +class TransformerUnitDecoder(TransformerDecoder): + """Based on Transformer decoder, with support to decoding stacked units""" + + def __init__( + self, + args, + dictionary, + embed_tokens, + no_encoder_attn=False, + output_projection=None, + ): + super().__init__( + args, dictionary, embed_tokens, no_encoder_attn, output_projection + ) + self.n_frames_per_step = args.n_frames_per_step + + self.out_proj_n_frames = ( + Linear( + self.output_embed_dim, + self.output_embed_dim * self.n_frames_per_step, + bias=False, + ) + if self.n_frames_per_step > 1 + else None + ) + + def forward( + self, + prev_output_tokens, + encoder_out: Optional[Dict[str, List[Tensor]]] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + features_only: bool = False, + full_context_alignment: bool = False, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + src_lengths: Optional[Any] = None, + return_all_hiddens: bool = False, + ): + """ + Args: + prev_output_tokens (LongTensor): previous decoder outputs of shape + `(batch, tgt_len)`, for teacher forcing + encoder_out (optional): output from the encoder, used for + encoder-side attention, should be of size T x B x C + incremental_state (dict): dictionary used for storing state during + :ref:`Incremental decoding` + features_only (bool, optional): only return features without + applying output layer (default: False). + full_context_alignment (bool, optional): don't apply + auto-regressive mask to self-attention (default: False). + + Returns: + tuple: + - the decoder's output of shape `(batch, tgt_len, vocab)` + - a dictionary with any model-specific outputs + """ + + x, extra = self.extract_features( + prev_output_tokens, + encoder_out=encoder_out, + incremental_state=incremental_state, + full_context_alignment=full_context_alignment, + alignment_layer=alignment_layer, + alignment_heads=alignment_heads, + ) + + if not features_only: + bsz, seq_len, d = x.size() + if self.out_proj_n_frames: + x = self.out_proj_n_frames(x) + x = self.output_layer(x.view(bsz, seq_len, self.n_frames_per_step, d)) + x = x.view(bsz, seq_len * self.n_frames_per_step, -1) + if ( + incremental_state is None and self.n_frames_per_step > 1 + ): # teacher-forcing mode in training + x = x[ + :, : -(self.n_frames_per_step - 1), : + ] # remove extra frames after + + return x, extra + + def upgrade_state_dict_named(self, state_dict, name): + if self.n_frames_per_step > 1: + move_keys = [ + ( + f"{name}.project_in_dim.weight", + f"{name}.embed_tokens.project_in_dim.weight", + ) + ] + for from_k, to_k in move_keys: + if from_k in state_dict and to_k not in state_dict: + state_dict[to_k] = state_dict[from_k] + del state_dict[from_k] + + +class S2STransformerMultitaskModelBase(FairseqEncoderDecoderModel): + @classmethod + def build_encoder(cls, args): + encoder = S2STransformerEncoder(args) + pretraining_path = getattr(args, "load_pretrained_encoder_from", None) + if pretraining_path is not None: + if not Path(pretraining_path).exists(): + logger.warning( + f"skipped pretraining because {pretraining_path} does not exist" + ) + else: + encoder = checkpoint_utils.load_pretrained_component_from_model( + component=encoder, checkpoint=pretraining_path + ) + logger.info(f"loaded pretrained encoder from: {pretraining_path}") + return encoder + + @classmethod + def build_multitask_decoder(cls, args, tgt_dict, in_dim): + decoder_args = args.decoder_args + decoder_args.encoder_embed_dim = in_dim + if args.decoder_type == "transformer": + base_multitask_text_transformer_decoder_arch(decoder_args) + task_decoder = TransformerDecoder( + decoder_args, + tgt_dict, + embed_tokens=TransformerModelBase.build_embedding( + decoder_args, + tgt_dict, + decoder_args.decoder_embed_dim, + ), + ) + elif args.decoder_type == "ctc": + task_decoder = CTCDecoder( + dictionary=tgt_dict, + in_dim=in_dim, + ) + else: + raise NotImplementedError( + "currently only support multitask decoder_type 'transformer', 'ctc'" + ) + + return task_decoder + + @classmethod + def build_model(cls, args, task): + encoder = cls.build_encoder(args) + decoder = ( + cls.build_decoder(args, task.target_dictionary) + if task.args.target_is_code + else cls.build_decoder(args) + ) + base_model = cls(encoder, decoder) + + # set up multitask decoders + base_model.multitask_decoders = {} + for task_name, task_obj in task.multitask_tasks.items(): + in_dim = ( + args.encoder_embed_dim + if task_obj.args.input_from == "encoder" + else args.decoder_embed_dim + ) + task_decoder = cls.build_multitask_decoder( + task_obj.args, task_obj.target_dictionary, in_dim + ) + + setattr(base_model, f"{task_name}_decoder", task_decoder) + decoder_model_cls = ( + FairseqEncoderModel + if task_obj.args.decoder_type == "ctc" + else FairseqLanguageModel + ) + base_model.multitask_decoders[task_name] = decoder_model_cls( + getattr(base_model, f"{task_name}_decoder") + ) + + return base_model + + def forward_encoder(self, src_tokens, src_lengths, speaker=None, **kwargs): + return self.encoder( + src_tokens, src_lengths=src_lengths, tgt_speaker=speaker, **kwargs + ) + + +@register_model("s2ut_transformer") +class S2UTTransformerModel(S2STransformerMultitaskModelBase): + """ + Direct speech-to-speech translation model with S2T Transformer encoder + Transformer discrete unit decoder + https://arxiv.org/abs/2107.05604 + """ + + @staticmethod + def add_args(parser): + # input + parser.add_argument( + "--conv-kernel-sizes", + type=str, + metavar="N", + help="kernel sizes of Conv1d subsampling layers", + ) + parser.add_argument( + "--conv-channels", + type=int, + metavar="N", + help="# of channels in Conv1d subsampling layers", + ) + # Transformer + parser.add_argument( + "--activation-fn", + type=str, + default="relu", + choices=utils.get_available_activation_fns(), + help="activation function to use", + ) + parser.add_argument( + "--dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--attention-dropout", + type=float, + metavar="D", + help="dropout probability for attention weights", + ) + parser.add_argument( + "--activation-dropout", + "--relu-dropout", + type=float, + metavar="D", + help="dropout probability after activation in FFN.", + ) + parser.add_argument( + "--encoder-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension", + ) + parser.add_argument( + "--encoder-ffn-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension for FFN", + ) + parser.add_argument( + "--encoder-layers", type=int, metavar="N", help="num encoder layers" + ) + parser.add_argument( + "--encoder-attention-heads", + type=int, + metavar="N", + help="num encoder attention heads", + ) + parser.add_argument( + "--encoder-normalize-before", + action="store_true", + help="apply layernorm before each encoder block", + ) + parser.add_argument( + "--decoder-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension", + ) + parser.add_argument( + "--decoder-ffn-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension for FFN", + ) + parser.add_argument( + "--decoder-layers", type=int, metavar="N", help="num decoder layers" + ) + parser.add_argument( + "--decoder-attention-heads", + type=int, + metavar="N", + help="num decoder attention heads", + ) + parser.add_argument( + "--decoder-normalize-before", + action="store_true", + help="apply layernorm before each decoder block", + ) + parser.add_argument( + "--share-decoder-input-output-embed", + action="store_true", + help="share decoder input and output embeddings", + ) + parser.add_argument( + "--layernorm-embedding", + action="store_true", + help="add layernorm to embedding", + ) + parser.add_argument( + "--no-scale-embedding", + action="store_true", + help="if True, dont scale embeddings", + ) + parser.add_argument( + "--load-pretrained-encoder-from", + type=str, + metavar="STR", + help="model to take encoder weights from (for initialization)", + ) + parser.add_argument( + "--encoder-freezing-updates", + type=int, + metavar="N", + help="freeze encoder for first N updates", + ) + # speaker + parser.add_argument( + "--speaker-embed-dim", + type=int, + metavar="N", + help="speaker embedding dimension", + ) + + @classmethod + def build_decoder(cls, args, tgt_dict): + num_embeddings = len(tgt_dict) + padding_idx = tgt_dict.pad() + embed_tokens = StackedEmbedding( + num_embeddings, + args.decoder_embed_dim, + padding_idx, + num_stacked=args.n_frames_per_step, + ) + + return TransformerUnitDecoder( + args, + tgt_dict, + embed_tokens, + ) + + def forward( + self, + src_tokens, + src_lengths, + prev_output_tokens, + tgt_speaker=None, + return_all_hiddens=False, + ): + encoder_out = self.encoder( + src_tokens, + src_lengths=src_lengths, + tgt_speaker=tgt_speaker, + return_all_hiddens=return_all_hiddens, + ) + decoder_out = self.decoder( + prev_output_tokens, + encoder_out=encoder_out, + ) + if return_all_hiddens: + decoder_out[-1]["encoder_states"] = encoder_out["encoder_states"] + decoder_out[-1]["encoder_padding_mask"] = encoder_out[ + "encoder_padding_mask" + ] + return decoder_out + + +@register_model("s2spect_transformer") +class S2SpecTTransformerModel(S2STransformerMultitaskModelBase): + """ + Speech-to-spectrogram model with S2T Transformer encoder + TTS Transformer decoder + """ + + @staticmethod + def add_args(parser): + # input + parser.add_argument( + "--conv-kernel-sizes", + type=str, + metavar="N", + help="kernel sizes of Conv1d subsampling layers", + ) + parser.add_argument( + "--conv-channels", + type=int, + metavar="N", + help="# of channels in Conv1d subsampling layers", + ) + # Transformer + parser.add_argument( + "--activation-fn", + type=str, + default="relu", + choices=utils.get_available_activation_fns(), + help="activation function to use", + ) + parser.add_argument( + "--dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--attention-dropout", + type=float, + metavar="D", + help="dropout probability for attention weights", + ) + parser.add_argument( + "--activation-dropout", + "--relu-dropout", + type=float, + metavar="D", + help="dropout probability after activation in FFN.", + ) + parser.add_argument( + "--encoder-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension", + ) + parser.add_argument( + "--encoder-ffn-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension for FFN", + ) + parser.add_argument( + "--encoder-layers", type=int, metavar="N", help="num encoder layers" + ) + parser.add_argument( + "--encoder-attention-heads", + type=int, + metavar="N", + help="num encoder attention heads", + ) + parser.add_argument( + "--encoder-normalize-before", + action="store_true", + help="apply layernorm before each encoder block", + ) + parser.add_argument( + "--no-scale-embedding", + action="store_true", + help="if True, dont scale embeddings", + ) + parser.add_argument( + "--load-pretrained-encoder-from", + type=str, + metavar="STR", + help="model to take encoder weights from (for initialization)", + ) + parser.add_argument( + "--encoder-freezing-updates", + type=int, + metavar="N", + help="freeze encoder for first N updates", + ) + # speaker + parser.add_argument( + "--speaker-embed-dim", + type=int, + metavar="N", + help="speaker embedding dimension", + ) + # decoder + parser.add_argument("--output-frame-dim", type=int) + # decoder prenet + parser.add_argument("--prenet-dropout", type=float) + parser.add_argument("--prenet-layers", type=int) + parser.add_argument("--prenet-dim", type=int) + # decoder postnet + parser.add_argument("--postnet-dropout", type=float) + parser.add_argument("--postnet-layers", type=int) + parser.add_argument("--postnet-conv-dim", type=int) + parser.add_argument("--postnet-conv-kernel-size", type=int) + # decoder transformer layers + parser.add_argument("--decoder-transformer-layers", type=int) + parser.add_argument("--decoder-embed-dim", type=int) + parser.add_argument("--decoder-ffn-embed-dim", type=int) + parser.add_argument("--decoder-normalize-before", action="store_true") + parser.add_argument("--decoder-attention-heads", type=int) + + @classmethod + def build_decoder(cls, args): + return TTSTransformerDecoder(args, None, padding_idx=1) + + def forward( + self, + src_tokens, + src_lengths, + prev_output_tokens, + tgt_speaker=None, + incremental_state=None, + target_lengths=None, + speaker=None, + return_all_hiddens=False, + ): + encoder_out = self.encoder( + src_tokens, + src_lengths=src_lengths, + tgt_speaker=tgt_speaker, + return_all_hiddens=return_all_hiddens, + ) + decoder_out = self.decoder( + prev_output_tokens, + encoder_out=encoder_out, + incremental_state=incremental_state, + target_lengths=target_lengths, + speaker=speaker, + ) + if return_all_hiddens: + decoder_out[-1]["encoder_states"] = encoder_out["encoder_states"] + decoder_out[-1]["encoder_padding_mask"] = encoder_out[ + "encoder_padding_mask" + ] + return decoder_out + + +def base_multitask_text_transformer_decoder_arch(args): + args.dropout = getattr(args, "dropout", 0.3) + args.decoder_layerdrop = getattr(args, "decoder_layerdrop", 0.0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", True + ) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 256) + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + args.max_target_positions = getattr(args, "max_target_positions", 1024) + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + + args.adaptive_input = getattr(args, "adaptive_input", False) + args.quant_noise_pq = getattr(args, "quant_noise_pq", 0) + + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + + args.decoder_layers = getattr(args, "decoder_layers", 2) + + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + + # decoder layer + args.activation_dropout = getattr(args, "activation_dropout", args.dropout) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", True) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 2048) + + args.attention_dropout = getattr(args, "attention_dropout", args.dropout) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 4) + + +def base_s2st_transformer_encoder_architecture(args): + args.encoder_freezing_updates = getattr(args, "encoder_freezing_updates", 0) + + # Convolutional subsampler + args.conv_kernel_sizes = getattr(args, "conv_kernel_sizes", "5,5") + args.conv_channels = getattr(args, "conv_channels", 1024) + # Transformer + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 12) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", True) + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", args.dropout) + args.activation_dropout = getattr(args, "activation_dropout", args.dropout) + args.activation_fn = getattr(args, "activation_fn", "relu") + + args.speaker_embed_dim = getattr(args, "speaker_embed_dim", 256) + + +@register_model_architecture( + model_name="s2ut_transformer", arch_name="s2ut_transformer" +) +def s2ut_architecture_base(args): + base_s2st_transformer_encoder_architecture(args) + + # decoder + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", True) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.decoder_layerdrop = getattr(args, "decoder_layerdrop", 0.0) + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + args.quant_noise_pq = getattr(args, "quant_noise_pq", 0) + + +@register_model_architecture("s2ut_transformer", "s2ut_transformer_fisher") +def s2ut_architecture_fisher(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.dropout = getattr(args, "dropout", 0.1) + + s2ut_architecture_base(args) + + +@register_model_architecture( + model_name="s2spect_transformer", arch_name="s2spect_transformer" +) +def s2spect_architecture_base(args): + base_s2st_transformer_encoder_architecture(args) + + # decoder + args.output_frame_dim = getattr(args, "output_frame_dim", 80) + # decoder prenet + args.prenet_dropout = getattr(args, "prenet_dropout", 0.5) + args.prenet_layers = getattr(args, "prenet_layers", 2) + args.prenet_dim = getattr(args, "prenet_dim", 256) + # decoder postnet + args.postnet_dropout = getattr(args, "postnet_dropout", 0.5) + args.postnet_layers = getattr(args, "postnet_layers", 5) + args.postnet_conv_dim = getattr(args, "postnet_conv_dim", 512) + args.postnet_conv_kernel_size = getattr(args, "postnet_conv_kernel_size", 5) + # decoder transformer layers + args.decoder_transformer_layers = getattr(args, "decoder_transformer_layers", 6) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", 4 * args.decoder_embed_dim + ) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 4) + + +@register_model_architecture("s2spect_transformer", "s2spect_transformer_fisher") +def s2spect_architecture_fisher(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 256 * 8) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.dropout = getattr(args, "dropout", 0.1) + + # decoder + args.prenet_dim = getattr(args, "prenet_dim", 32) + + s2spect_architecture_base(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/__init__.py new file mode 100644 index 00000000..f49c88e5 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/__init__.py @@ -0,0 +1,12 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .berard import * # noqa +from .convtransformer import * # noqa +from .multi_modality_model import * # noqa +from .s2t_transformer import * # noqa +from .s2t_wav_transformer import * # noqa +from .xm_transformer import * # noqa +from .s2t_conformer import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/berard.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/berard.py new file mode 100644 index 00000000..c505e3ac --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/berard.py @@ -0,0 +1,606 @@ +#!/usr/bin/env python3 + +from ast import literal_eval +from typing import List, Tuple + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import checkpoint_utils, utils +from fairseq.data.data_utils import lengths_to_padding_mask +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + FairseqIncrementalDecoder, + register_model, + register_model_architecture, +) + + +@register_model("s2t_berard") +class BerardModel(FairseqEncoderDecoderModel): + """Implementation of a model similar to https://arxiv.org/abs/1802.04200 + + Paper title: End-to-End Automatic Speech Translation of Audiobooks + An implementation is available in tensorflow at + https://github.com/eske/seq2seq + Relevant files in this implementation are the config + (https://github.com/eske/seq2seq/blob/master/config/LibriSpeech/AST.yaml) + and the model code + (https://github.com/eske/seq2seq/blob/master/translate/models.py). + The encoder and decoder try to be close to the original implementation. + The attention is an MLP as in Bahdanau et al. + (https://arxiv.org/abs/1409.0473). + There is no state initialization by averaging the encoder outputs. + """ + + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + + @staticmethod + def add_args(parser): + parser.add_argument( + "--input-layers", + type=str, + metavar="EXPR", + help="List of linear layer dimensions. These " + "layers are applied to the input features and " + "are followed by tanh and possibly dropout.", + ) + parser.add_argument( + "--dropout", + type=float, + metavar="D", + help="Dropout probability to use in the encoder/decoder. " + "Note that this parameters control dropout in various places, " + "there is no fine-grained control for dropout for embeddings " + "vs LSTM layers for example.", + ) + parser.add_argument( + "--in-channels", + type=int, + metavar="N", + help="Number of encoder input channels. " "Typically value is 1.", + ) + parser.add_argument( + "--conv-layers", + type=str, + metavar="EXPR", + help="List of conv layers " "(format: (channels, kernel, stride)).", + ) + parser.add_argument( + "--num-blstm-layers", + type=int, + metavar="N", + help="Number of encoder bi-LSTM layers.", + ) + parser.add_argument( + "--lstm-size", type=int, metavar="N", help="LSTM hidden size." + ) + parser.add_argument( + "--decoder-embed-dim", + type=int, + metavar="N", + help="Embedding dimension of the decoder target tokens.", + ) + parser.add_argument( + "--decoder-hidden-dim", + type=int, + metavar="N", + help="Decoder LSTM hidden dimension.", + ) + parser.add_argument( + "--decoder-num-layers", + type=int, + metavar="N", + help="Number of decoder LSTM layers.", + ) + parser.add_argument( + "--attention-dim", + type=int, + metavar="N", + help="Hidden layer dimension in MLP attention.", + ) + parser.add_argument( + "--output-layer-dim", + type=int, + metavar="N", + help="Hidden layer dim for linear layer prior to output projection.", + ) + parser.add_argument( + "--load-pretrained-encoder-from", + type=str, + metavar="STR", + help="model to take encoder weights from (for initialization)", + ) + parser.add_argument( + "--load-pretrained-decoder-from", + type=str, + metavar="STR", + help="model to take decoder weights from (for initialization)", + ) + + @classmethod + def build_encoder(cls, args, task): + encoder = BerardEncoder( + input_layers=literal_eval(args.input_layers), + conv_layers=literal_eval(args.conv_layers), + in_channels=args.input_channels, + input_feat_per_channel=args.input_feat_per_channel, + num_blstm_layers=args.num_blstm_layers, + lstm_size=args.lstm_size, + dropout=args.dropout, + ) + if getattr(args, "load_pretrained_encoder_from", None): + encoder = checkpoint_utils.load_pretrained_component_from_model( + component=encoder, checkpoint=args.load_pretrained_encoder_from + ) + return encoder + + @classmethod + def build_decoder(cls, args, task): + decoder = LSTMDecoder( + dictionary=task.target_dictionary, + embed_dim=args.decoder_embed_dim, + num_layers=args.decoder_num_layers, + hidden_size=args.decoder_hidden_dim, + dropout=args.dropout, + encoder_output_dim=2 * args.lstm_size, # bidirectional + attention_dim=args.attention_dim, + output_layer_dim=args.output_layer_dim, + ) + if getattr(args, "load_pretrained_decoder_from", None): + decoder = checkpoint_utils.load_pretrained_component_from_model( + component=decoder, checkpoint=args.load_pretrained_decoder_from + ) + return decoder + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + encoder = cls.build_encoder(args, task) + decoder = cls.build_decoder(args, task) + + return cls(encoder, decoder) + + def get_normalized_probs(self, net_output, log_probs, sample=None): + # net_output['encoder_out'] is a (B, T, D) tensor + lprobs = super().get_normalized_probs(net_output, log_probs, sample) + # lprobs is a (B, T, D) tensor + lprobs.batch_first = True + return lprobs + + +class BerardEncoder(FairseqEncoder): + def __init__( + self, + input_layers: List[int], + conv_layers: List[Tuple[int]], + in_channels: int, + input_feat_per_channel: int, + num_blstm_layers: int, + lstm_size: int, + dropout: float, + ): + """ + Args: + input_layers: list of linear layer dimensions. These layers are + applied to the input features and are followed by tanh and + possibly dropout. + conv_layers: list of conv2d layer configurations. A configuration is + a tuple (out_channels, conv_kernel_size, stride). + in_channels: number of input channels. + input_feat_per_channel: number of input features per channel. These + are speech features, typically 40 or 80. + num_blstm_layers: number of bidirectional LSTM layers. + lstm_size: size of the LSTM hidden (and cell) size. + dropout: dropout probability. Dropout can be applied after the + linear layers and LSTM layers but not to the convolutional + layers. + """ + super().__init__(None) + + self.input_layers = nn.ModuleList() + in_features = input_feat_per_channel + for out_features in input_layers: + if dropout > 0: + self.input_layers.append( + nn.Sequential( + nn.Linear(in_features, out_features), nn.Dropout(p=dropout) + ) + ) + else: + self.input_layers.append(nn.Linear(in_features, out_features)) + in_features = out_features + + self.in_channels = in_channels + self.input_dim = input_feat_per_channel + self.conv_kernel_sizes_and_strides = [] + self.conv_layers = nn.ModuleList() + lstm_input_dim = input_layers[-1] + for conv_layer in conv_layers: + out_channels, conv_kernel_size, conv_stride = conv_layer + self.conv_layers.append( + nn.Conv2d( + in_channels, + out_channels, + conv_kernel_size, + stride=conv_stride, + padding=conv_kernel_size // 2, + ) + ) + self.conv_kernel_sizes_and_strides.append((conv_kernel_size, conv_stride)) + in_channels = out_channels + lstm_input_dim //= conv_stride + + lstm_input_dim *= conv_layers[-1][0] + self.lstm_size = lstm_size + self.num_blstm_layers = num_blstm_layers + self.lstm = nn.LSTM( + input_size=lstm_input_dim, + hidden_size=lstm_size, + num_layers=num_blstm_layers, + dropout=dropout, + bidirectional=True, + ) + self.output_dim = 2 * lstm_size # bidirectional + if dropout > 0: + self.dropout = nn.Dropout(p=dropout) + else: + self.dropout = None + + def forward(self, src_tokens, src_lengths=None, **kwargs): + """ + Args + src_tokens: padded tensor (B, T, C * feat) + src_lengths: tensor of original lengths of input utterances (B,) + """ + bsz, max_seq_len, _ = src_tokens.size() + # (B, C, T, feat) + x = ( + src_tokens.view(bsz, max_seq_len, self.in_channels, self.input_dim) + .transpose(1, 2) + .contiguous() + ) + + for input_layer in self.input_layers: + x = input_layer(x) + x = torch.tanh(x) + + for conv_layer in self.conv_layers: + x = conv_layer(x) + + bsz, _, output_seq_len, _ = x.size() + + # (B, C, T, feat) -> (B, T, C, feat) -> (T, B, C, feat) -> + # (T, B, C * feat) + x = x.transpose(1, 2).transpose(0, 1).contiguous().view(output_seq_len, bsz, -1) + + input_lengths = src_lengths.clone() + for k, s in self.conv_kernel_sizes_and_strides: + p = k // 2 + input_lengths = (input_lengths.float() + 2 * p - k) / s + 1 + input_lengths = input_lengths.floor().long() + + packed_x = nn.utils.rnn.pack_padded_sequence(x, input_lengths) + + h0 = x.new(2 * self.num_blstm_layers, bsz, self.lstm_size).zero_() + c0 = x.new(2 * self.num_blstm_layers, bsz, self.lstm_size).zero_() + packed_outs, _ = self.lstm(packed_x, (h0, c0)) + + # unpack outputs and apply dropout + x, output_lengths = nn.utils.rnn.pad_packed_sequence(packed_outs) + if self.dropout is not None: + x = self.dropout(x) + + encoder_padding_mask = ( + lengths_to_padding_mask(output_lengths).to(src_tokens.device).t() + ) + + return { + "encoder_out": x, # (T, B, C) + "encoder_padding_mask": encoder_padding_mask, # (T, B) + } + + def reorder_encoder_out(self, encoder_out, new_order): + encoder_out["encoder_out"] = encoder_out["encoder_out"].index_select( + 1, new_order + ) + encoder_out["encoder_padding_mask"] = encoder_out[ + "encoder_padding_mask" + ].index_select(1, new_order) + return encoder_out + + +class MLPAttention(nn.Module): + """The original attention from Badhanau et al. (2014) + + https://arxiv.org/abs/1409.0473, based on a Multi-Layer Perceptron. + The attention score between position i in the encoder and position j in the + decoder is: alpha_ij = V_a * tanh(W_ae * enc_i + W_ad * dec_j + b_a) + """ + + def __init__(self, decoder_hidden_state_dim, context_dim, attention_dim): + super().__init__() + + self.context_dim = context_dim + self.attention_dim = attention_dim + # W_ae and b_a + self.encoder_proj = nn.Linear(context_dim, self.attention_dim, bias=True) + # W_ad + self.decoder_proj = nn.Linear( + decoder_hidden_state_dim, self.attention_dim, bias=False + ) + # V_a + self.to_scores = nn.Linear(self.attention_dim, 1, bias=False) + + def forward(self, decoder_state, source_hids, encoder_padding_mask): + """The expected input dimensions are: + decoder_state: bsz x decoder_hidden_state_dim + source_hids: src_len x bsz x context_dim + encoder_padding_mask: src_len x bsz + """ + src_len, bsz, _ = source_hids.size() + # (src_len*bsz) x context_dim (to feed through linear) + flat_source_hids = source_hids.view(-1, self.context_dim) + # (src_len*bsz) x attention_dim + encoder_component = self.encoder_proj(flat_source_hids) + # src_len x bsz x attention_dim + encoder_component = encoder_component.view(src_len, bsz, self.attention_dim) + # 1 x bsz x attention_dim + decoder_component = self.decoder_proj(decoder_state).unsqueeze(0) + # Sum with broadcasting and apply the non linearity + # src_len x bsz x attention_dim + hidden_att = torch.tanh( + (decoder_component + encoder_component).view(-1, self.attention_dim) + ) + # Project onto the reals to get attentions scores (src_len x bsz) + attn_scores = self.to_scores(hidden_att).view(src_len, bsz) + + # Mask + softmax (src_len x bsz) + if encoder_padding_mask is not None: + attn_scores = ( + attn_scores.float() + .masked_fill_(encoder_padding_mask, float("-inf")) + .type_as(attn_scores) + ) # FP16 support: cast to float and back + # srclen x bsz + normalized_masked_attn_scores = F.softmax(attn_scores, dim=0) + + # Sum weighted sources (bsz x context_dim) + attn_weighted_context = ( + source_hids * normalized_masked_attn_scores.unsqueeze(2) + ).sum(dim=0) + + return attn_weighted_context, normalized_masked_attn_scores + + +class LSTMDecoder(FairseqIncrementalDecoder): + def __init__( + self, + dictionary, + embed_dim, + num_layers, + hidden_size, + dropout, + encoder_output_dim, + attention_dim, + output_layer_dim, + ): + """ + Args: + dictionary: target text dictionary. + embed_dim: embedding dimension for target tokens. + num_layers: number of LSTM layers. + hidden_size: hidden size for LSTM layers. + dropout: dropout probability. Dropout can be applied to the + embeddings, the LSTM layers, and the context vector. + encoder_output_dim: encoder output dimension (hidden size of + encoder LSTM). + attention_dim: attention dimension for MLP attention. + output_layer_dim: size of the linear layer prior to output + projection. + """ + super().__init__(dictionary) + self.num_layers = num_layers + self.hidden_size = hidden_size + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + self.embed_tokens = nn.Embedding(num_embeddings, embed_dim, padding_idx) + if dropout > 0: + self.dropout = nn.Dropout(p=dropout) + else: + self.dropout = None + + self.layers = nn.ModuleList() + for layer_id in range(num_layers): + input_size = embed_dim if layer_id == 0 else encoder_output_dim + self.layers.append( + nn.LSTMCell(input_size=input_size, hidden_size=hidden_size) + ) + + self.context_dim = encoder_output_dim + self.attention = MLPAttention( + decoder_hidden_state_dim=hidden_size, + context_dim=encoder_output_dim, + attention_dim=attention_dim, + ) + + self.deep_output_layer = nn.Linear( + hidden_size + encoder_output_dim + embed_dim, output_layer_dim + ) + self.output_projection = nn.Linear(output_layer_dim, num_embeddings) + + def forward( + self, prev_output_tokens, encoder_out=None, incremental_state=None, **kwargs + ): + encoder_padding_mask = encoder_out["encoder_padding_mask"] + encoder_outs = encoder_out["encoder_out"] + + if incremental_state is not None: + prev_output_tokens = prev_output_tokens[:, -1:] + bsz, seqlen = prev_output_tokens.size() + + srclen = encoder_outs.size(0) + + # embed tokens + embeddings = self.embed_tokens(prev_output_tokens) + x = embeddings + if self.dropout is not None: + x = self.dropout(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + # initialize previous states (or get from cache during incremental + # generation) + cached_state = utils.get_incremental_state( + self, incremental_state, "cached_state" + ) + if cached_state is not None: + prev_hiddens, prev_cells = cached_state + else: + prev_hiddens = [encoder_out["encoder_out"].mean(dim=0)] * self.num_layers + prev_cells = [x.new_zeros(bsz, self.hidden_size)] * self.num_layers + + attn_scores = x.new_zeros(bsz, srclen) + attention_outs = [] + outs = [] + for j in range(seqlen): + input = x[j, :, :] + attention_out = None + for i, layer in enumerate(self.layers): + # the previous state is one layer below except for the bottom + # layer where the previous state is the state emitted by the + # top layer + hidden, cell = layer( + input, + ( + prev_hiddens[(i - 1) % self.num_layers], + prev_cells[(i - 1) % self.num_layers], + ), + ) + if self.dropout is not None: + hidden = self.dropout(hidden) + prev_hiddens[i] = hidden + prev_cells[i] = cell + if attention_out is None: + attention_out, attn_scores = self.attention( + hidden, encoder_outs, encoder_padding_mask + ) + if self.dropout is not None: + attention_out = self.dropout(attention_out) + attention_outs.append(attention_out) + input = attention_out + + # collect the output of the top layer + outs.append(hidden) + + # cache previous states (no-op except during incremental generation) + utils.set_incremental_state( + self, incremental_state, "cached_state", (prev_hiddens, prev_cells) + ) + + # collect outputs across time steps + x = torch.cat(outs, dim=0).view(seqlen, bsz, self.hidden_size) + attention_outs_concat = torch.cat(attention_outs, dim=0).view( + seqlen, bsz, self.context_dim + ) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + attention_outs_concat = attention_outs_concat.transpose(0, 1) + + # concat LSTM output, attention output and embedding + # before output projection + x = torch.cat((x, attention_outs_concat, embeddings), dim=2) + x = self.deep_output_layer(x) + x = torch.tanh(x) + if self.dropout is not None: + x = self.dropout(x) + # project back to size of vocabulary + x = self.output_projection(x) + + # to return the full attn_scores tensor, we need to fix the decoder + # to account for subsampling input frames + # return x, attn_scores + return x, None + + def reorder_incremental_state(self, incremental_state, new_order): + super().reorder_incremental_state(incremental_state, new_order) + cached_state = utils.get_incremental_state( + self, incremental_state, "cached_state" + ) + if cached_state is None: + return + + def reorder_state(state): + if isinstance(state, list): + return [reorder_state(state_i) for state_i in state] + return state.index_select(0, new_order) + + new_state = tuple(map(reorder_state, cached_state)) + utils.set_incremental_state(self, incremental_state, "cached_state", new_state) + + +@register_model_architecture(model_name="s2t_berard", arch_name="s2t_berard") +def berard(args): + """The original version: "End-to-End Automatic Speech Translation of + Audiobooks" (https://arxiv.org/abs/1802.04200) + """ + args.input_layers = getattr(args, "input_layers", "[256, 128]") + args.conv_layers = getattr(args, "conv_layers", "[(16, 3, 2), (16, 3, 2)]") + args.num_blstm_layers = getattr(args, "num_blstm_layers", 3) + args.lstm_size = getattr(args, "lstm_size", 256) + args.dropout = getattr(args, "dropout", 0.2) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 128) + args.decoder_num_layers = getattr(args, "decoder_num_layers", 2) + args.decoder_hidden_dim = getattr(args, "decoder_hidden_dim", 512) + args.attention_dim = getattr(args, "attention_dim", 512) + args.output_layer_dim = getattr(args, "output_layer_dim", 128) + args.load_pretrained_encoder_from = getattr( + args, "load_pretrained_encoder_from", None + ) + args.load_pretrained_decoder_from = getattr( + args, "load_pretrained_decoder_from", None + ) + + +@register_model_architecture(model_name="s2t_berard", arch_name="s2t_berard_256_3_3") +def berard_256_3_3(args): + """Used in + * "Harnessing Indirect Training Data for End-to-End Automatic Speech + Translation: Tricks of the Trade" (https://arxiv.org/abs/1909.06515) + * "CoVoST: A Diverse Multilingual Speech-To-Text Translation Corpus" + (https://arxiv.org/pdf/2002.01320.pdf) + * "Self-Supervised Representations Improve End-to-End Speech Translation" + (https://arxiv.org/abs/2006.12124) + """ + args.decoder_num_layers = getattr(args, "decoder_num_layers", 3) + berard(args) + + +@register_model_architecture(model_name="s2t_berard", arch_name="s2t_berard_512_3_2") +def berard_512_3_2(args): + args.num_blstm_layers = getattr(args, "num_blstm_layers", 3) + args.lstm_size = getattr(args, "lstm_size", 512) + args.dropout = getattr(args, "dropout", 0.3) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 256) + args.decoder_num_layers = getattr(args, "decoder_num_layers", 2) + args.decoder_hidden_dim = getattr(args, "decoder_hidden_dim", 1024) + args.attention_dim = getattr(args, "attention_dim", 512) + args.output_layer_dim = getattr(args, "output_layer_dim", 256) + berard(args) + + +@register_model_architecture(model_name="s2t_berard", arch_name="s2t_berard_512_5_3") +def berard_512_5_3(args): + args.num_blstm_layers = getattr(args, "num_blstm_layers", 5) + args.lstm_size = getattr(args, "lstm_size", 512) + args.dropout = getattr(args, "dropout", 0.3) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 256) + args.decoder_num_layers = getattr(args, "decoder_num_layers", 3) + args.decoder_hidden_dim = getattr(args, "decoder_hidden_dim", 1024) + args.attention_dim = getattr(args, "attention_dim", 512) + args.output_layer_dim = getattr(args, "output_layer_dim", 256) + berard(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/convtransformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/convtransformer.py new file mode 100644 index 00000000..eba000d7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/convtransformer.py @@ -0,0 +1,448 @@ +#!/usr/bin/env python3 + +import logging +import math +from typing import Dict, List, Optional, Tuple + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import checkpoint_utils, utils +from fairseq.data.data_utils import lengths_to_padding_mask +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + register_model, + register_model_architecture, +) +from fairseq.models.transformer import Embedding, TransformerDecoder +from fairseq.modules import LayerNorm, PositionalEmbedding, TransformerEncoderLayer +from torch import Tensor + +logger = logging.getLogger(__name__) + + +@register_model("convtransformer") +class ConvTransformerModel(FairseqEncoderDecoderModel): + """ + Transformer-based Speech translation model from ESPNet-ST + https://arxiv.org/abs/2004.10234 + """ + + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + parser.add_argument( + "--input-feat-per-channel", + type=int, + metavar="N", + help="encoder input dimension per input channel", + ) + parser.add_argument( + "--activation-fn", + choices=utils.get_available_activation_fns(), + help="activation function to use", + ) + parser.add_argument( + "--dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--attention-dropout", + type=float, + metavar="D", + help="dropout probability for attention weights", + ) + parser.add_argument( + "--activation-dropout", + "--relu-dropout", + type=float, + metavar="D", + help="dropout probability after activation in FFN.", + ) + parser.add_argument( + "--encoder-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension", + ) + parser.add_argument( + "--encoder-ffn-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension for FFN", + ) + parser.add_argument( + "--encoder-layers", type=int, metavar="N", help="num encoder layers" + ) + parser.add_argument( + "--encoder-attention-heads", + type=int, + metavar="N", + help="num encoder attention heads", + ) + parser.add_argument( + "--encoder-normalize-before", + action="store_true", + help="apply layernorm before each encoder block", + ) + parser.add_argument( + "--decoder-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension", + ) + parser.add_argument( + "--decoder-ffn-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension for FFN", + ) + parser.add_argument( + "--decoder-layers", type=int, metavar="N", help="num decoder layers" + ) + parser.add_argument( + "--decoder-attention-heads", + type=int, + metavar="N", + help="num decoder attention heads", + ) + parser.add_argument( + "--decoder-normalize-before", + action="store_true", + help="apply layernorm before each decoder block", + ) + parser.add_argument( + "--decoder-output-dim", + type=int, + metavar="N", + help="decoder output dimension (extra linear layer if different from decoder embed dim)", + ) + parser.add_argument( + "--share-decoder-input-output-embed", + action="store_true", + help="share decoder input and output embeddings", + ) + parser.add_argument( + "--layernorm-embedding", + action="store_true", + help="add layernorm to embedding", + ) + parser.add_argument( + "--no-scale-embedding", + action="store_true", + help="if True, dont scale embeddings", + ) + parser.add_argument( + "--load-pretrained-encoder-from", + type=str, + metavar="STR", + help="model to take encoder weights from (for initialization)", + ) + parser.add_argument( + "--load-pretrained-decoder-from", + type=str, + metavar="STR", + help="model to take decoder weights from (for initialization)", + ) + parser.add_argument( + "--conv-out-channels", + type=int, + metavar="INT", + help="the number of output channels of conv layer", + ) + + @classmethod + def build_encoder(cls, args): + encoder = ConvTransformerEncoder(args) + if getattr(args, "load_pretrained_encoder_from", None): + encoder = checkpoint_utils.load_pretrained_component_from_model( + component=encoder, checkpoint=args.load_pretrained_encoder_from + ) + return encoder + + @classmethod + def build_decoder(cls, args, task, embed_tokens): + decoder = TransformerDecoderNoExtra(args, task.target_dictionary, embed_tokens) + if getattr(args, "load_pretrained_decoder_from", None): + decoder = checkpoint_utils.load_pretrained_component_from_model( + component=decoder, checkpoint=args.load_pretrained_decoder_from + ) + return decoder + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present in older models + base_architecture(args) + + def build_embedding(dictionary, embed_dim): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + return Embedding(num_embeddings, embed_dim, padding_idx) + + decoder_embed_tokens = build_embedding( + task.target_dictionary, args.decoder_embed_dim + ) + encoder = cls.build_encoder(args) + decoder = cls.build_decoder(args, task, decoder_embed_tokens) + return cls(encoder, decoder) + + @staticmethod + @torch.jit.unused + def set_batch_first(lprobs): + lprobs.batch_first = True + + def get_normalized_probs( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + log_probs: bool, + sample: Optional[Dict[str, Tensor]] = None, + ): + # net_output['encoder_out'] is a (B, T, D) tensor + lprobs = self.get_normalized_probs_scriptable(net_output, log_probs, sample) + if self.training: + self.set_batch_first(lprobs) + return lprobs + + def output_layout(self): + return "BTD" + + """ + The forward method inherited from the base class has a **kwargs argument in + its input, which is not supported in torchscript. This method overrites the forward + method definition without **kwargs. + """ + + def forward(self, src_tokens, src_lengths, prev_output_tokens): + encoder_out = self.encoder(src_tokens=src_tokens, src_lengths=src_lengths) + decoder_out = self.decoder( + prev_output_tokens=prev_output_tokens, encoder_out=encoder_out + ) + return decoder_out + + +class ConvTransformerEncoder(FairseqEncoder): + """Conv + Transformer encoder""" + + def __init__(self, args): + """Construct an Encoder object.""" + super().__init__(None) + + self.dropout = args.dropout + self.embed_scale = ( + 1.0 if args.no_scale_embedding else math.sqrt(args.encoder_embed_dim) + ) + self.padding_idx = 1 + self.in_channels = 1 + self.input_dim = args.input_feat_per_channel + self.conv = torch.nn.Sequential( + torch.nn.Conv2d(1, args.conv_out_channels, 3, stride=2, padding=3 // 2), + torch.nn.ReLU(), + torch.nn.Conv2d( + args.conv_out_channels, + args.conv_out_channels, + 3, + stride=2, + padding=3 // 2, + ), + torch.nn.ReLU(), + ) + transformer_input_dim = self.infer_conv_output_dim( + self.in_channels, self.input_dim, args.conv_out_channels + ) + self.out = torch.nn.Linear(transformer_input_dim, args.encoder_embed_dim) + self.embed_positions = PositionalEmbedding( + args.max_source_positions, + args.encoder_embed_dim, + self.padding_idx, + learned=False, + ) + + self.transformer_layers = nn.ModuleList([]) + self.transformer_layers.extend( + [TransformerEncoderLayer(args) for i in range(args.encoder_layers)] + ) + if args.encoder_normalize_before: + self.layer_norm = LayerNorm(args.encoder_embed_dim) + else: + self.layer_norm = None + + def pooling_ratio(self): + return 4 + + def infer_conv_output_dim(self, in_channels, input_dim, out_channels): + sample_seq_len = 200 + sample_bsz = 10 + x = torch.randn(sample_bsz, in_channels, sample_seq_len, input_dim) + x = torch.nn.Conv2d(1, out_channels, 3, stride=2, padding=3 // 2)(x) + x = torch.nn.Conv2d(out_channels, out_channels, 3, stride=2, padding=3 // 2)(x) + x = x.transpose(1, 2) + mb, seq = x.size()[:2] + return x.contiguous().view(mb, seq, -1).size(-1) + + def forward(self, src_tokens, src_lengths): + """Encode input sequence. + :param torch.Tensor xs: input tensor + :param torch.Tensor masks: input mask + :return: position embedded tensor and mask + :rtype Tuple[torch.Tensor, torch.Tensor]: + """ + bsz, max_seq_len, _ = src_tokens.size() + x = ( + src_tokens.view(bsz, max_seq_len, self.in_channels, self.input_dim) + .transpose(1, 2) + .contiguous() + ) + x = self.conv(x) + bsz, _, output_seq_len, _ = x.size() + x = x.transpose(1, 2).transpose(0, 1).contiguous().view(output_seq_len, bsz, -1) + x = self.out(x) + x = self.embed_scale * x + + subsampling_factor = int(max_seq_len * 1.0 / output_seq_len + 0.5) + input_len_0 = (src_lengths.float() / subsampling_factor).ceil().long() + input_len_1 = x.size(0) * torch.ones([src_lengths.size(0)]).long().to( + input_len_0.device + ) + input_lengths = torch.min(input_len_0, input_len_1) + + encoder_padding_mask = lengths_to_padding_mask(input_lengths) + + positions = self.embed_positions(encoder_padding_mask).transpose(0, 1) + x += positions + x = F.dropout(x, p=self.dropout, training=self.training) + + for layer in self.transformer_layers: + x = layer(x, encoder_padding_mask) + + if not encoder_padding_mask.any(): + maybe_encoder_padding_mask = None + else: + maybe_encoder_padding_mask = encoder_padding_mask + + return { + "encoder_out": [x], + "encoder_padding_mask": [maybe_encoder_padding_mask] + if maybe_encoder_padding_mask is not None + else [], + "encoder_embedding": [], + "encoder_states": [], + "src_tokens": [], + "src_lengths": [], + } + + @torch.jit.export + def reorder_encoder_out(self, encoder_out: Dict[str, List[Tensor]], new_order): + """ + Reorder encoder output according to *new_order*. + + Args: + encoder_out: output from the ``forward()`` method + new_order (LongTensor): desired order + + Returns: + *encoder_out* rearranged according to *new_order* + """ + new_encoder_out = [encoder_out["encoder_out"][0].index_select(1, new_order)] + if len(encoder_out["encoder_padding_mask"]) == 0: + new_encoder_padding_mask = [] + else: + new_encoder_padding_mask = [ + (encoder_out["encoder_padding_mask"][0]).index_select(0, new_order) + ] + if len(encoder_out["encoder_embedding"]) == 0: + new_encoder_embedding = [] + else: + new_encoder_embedding = [ + (encoder_out["encoder_embedding"][0]).index_select(0, new_order) + ] + encoder_states = encoder_out["encoder_states"] + if len(encoder_states) > 0: + for idx, state in enumerate(encoder_states): + encoder_states[idx] = state.index_select(1, new_order) + + return { + "encoder_out": new_encoder_out, + "encoder_padding_mask": new_encoder_padding_mask, + "encoder_embedding": new_encoder_embedding, + "encoder_states": encoder_states, + "src_tokens": [], + "src_lengths": [], + } + + +class TransformerDecoderNoExtra(TransformerDecoder): + def extract_features( + self, + prev_output_tokens, + encoder_out: Optional[Dict[str, List[Tensor]]], + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + full_context_alignment: bool = False, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + ): + # call scriptable method from parent class + x, _ = self.extract_features_scriptable( + prev_output_tokens, + encoder_out, + incremental_state, + full_context_alignment, + alignment_layer, + alignment_heads, + ) + return x, None + + +@register_model_architecture(model_name="convtransformer", arch_name="convtransformer") +def base_architecture(args): + args.input_feat_per_channel = getattr(args, "input_feat_per_channel", 80) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.dropout = getattr(args, "dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.decoder_layerdrop = getattr(args, "decoder_layerdrop", 0.0) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + args.quant_noise_pq = getattr(args, "quant_noise_pq", 0) + args.max_source_positions = getattr(args, "max_source_positions", 3000) + args.max_target_positions = getattr(args, "max_target_positions", 1024) + args.tie_adaptive_weights = getattr(args, "tie_adaptive_weights", False) + args.conv_out_channels = getattr(args, "conv_out_channels", args.encoder_embed_dim) + + +@register_model_architecture("convtransformer", "convtransformer_espnet") +def convtransformer_espnet(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_layers = getattr(args, "encoder_layers", 12) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 4) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/hub_interface.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/hub_interface.py new file mode 100644 index 00000000..ff6fd638 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/hub_interface.py @@ -0,0 +1,126 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from argparse import Namespace +import logging +from typing import Union, Tuple, Optional + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from fairseq.data import encoders +from fairseq.data.audio.audio_utils import ( + get_waveform as get_wav, + convert_waveform as convert_wav, + get_fbank, +) +import fairseq.data.audio.feature_transforms.utterance_cmvn as utt_cmvn +from fairseq.data.audio.speech_to_text_dataset import SpeechToTextDataset + +logger = logging.getLogger(__name__) + + +class S2THubInterface(nn.Module): + def __init__(self, cfg, task, model): + super().__init__() + self.cfg = cfg + self.task = task + self.model = model + self.model.eval() + self.generator = self.task.build_generator([self.model], self.cfg) + + @classmethod + def get_model_input(cls, task, audio: Union[str, torch.Tensor]): + input_type = task.data_cfg.hub.get("input_type", "fbank80") + if input_type == "fbank80_w_utt_cmvn": + if isinstance(audio, str): + feat = utt_cmvn.UtteranceCMVN()(get_fbank(audio)) + feat = feat.unsqueeze(0) # T x D -> 1 x T x D + else: + import torchaudio.compliance.kaldi as kaldi + + feat = kaldi.fbank(audio, num_mel_bins=80).numpy() # 1 x T x D + elif input_type in {"waveform", "standardized_waveform"}: + if isinstance(audio, str): + feat, sr = get_wav(audio) # C x T + feat, _ = convert_wav( + feat, sr, to_sample_rate=16_000, to_mono=True + ) # C x T -> 1 x T + else: + feat = audio.numpy() + else: + raise ValueError(f"Unknown value: input_type = {input_type}") + + src_lengths = torch.Tensor([feat.shape[1]]).long() + src_tokens = torch.from_numpy(feat) # 1 x T (x D) + if input_type == "standardized_waveform": + with torch.no_grad(): + src_tokens = F.layer_norm(src_tokens, src_tokens.shape) + + return { + "net_input": { + "src_tokens": src_tokens, + "src_lengths": src_lengths, + "prev_output_tokens": None, + }, + "target_lengths": None, + "speaker": None, + } + + @classmethod + def detokenize(cls, task, tokens): + text = task.tgt_dict.string(tokens) + tkn_cfg = task.data_cfg.bpe_tokenizer + tokenizer = encoders.build_bpe(Namespace(**tkn_cfg)) + return text if tokenizer is None else tokenizer.decode(text) + + @classmethod + def get_prefix_token(cls, task, lang): + prefix_size = int(task.data_cfg.prepend_tgt_lang_tag) + prefix_tokens = None + if prefix_size > 0: + assert lang is not None + lang_tag = SpeechToTextDataset.get_lang_tag_idx(lang, task.tgt_dict) + prefix_tokens = torch.Tensor([lang_tag]).long().unsqueeze(0) + return prefix_tokens + + @classmethod + def get_prediction( + cls, task, model, generator, sample, tgt_lang=None, synthesize_speech=False + ) -> Union[str, Tuple[str, Tuple[torch.Tensor, int]]]: + _tgt_lang = tgt_lang or task.data_cfg.hub.get("tgt_lang", None) + prefix = cls.get_prefix_token(task, _tgt_lang) + pred_tokens = generator.generate([model], sample, prefix_tokens=prefix) + pred = cls.detokenize(task, pred_tokens[0][0]["tokens"]) + + if synthesize_speech: + pfx = f"{_tgt_lang}_" if task.data_cfg.prepend_tgt_lang_tag else "" + tts_model_id = task.data_cfg.hub.get(f"{pfx}tts_model_id", None) + if tts_model_id is None: + logger.warning("TTS model configuration not found") + else: + _repo, _id = tts_model_id.split(":") + tts_model = torch.hub.load(_repo, _id, verbose=False) + pred = (pred, tts_model.predict(pred)) + return pred + + def predict( + self, + audio: Union[str, torch.Tensor], + tgt_lang: Optional[str] = None, + synthesize_speech: bool = False, + ) -> Union[str, Tuple[str, Tuple[torch.Tensor, int]]]: + # `audio` is either a file path or a 1xT Tensor + # return either text or (text, synthetic speech) + sample = self.get_model_input(self.task, audio) + return self.get_prediction( + self.task, + self.model, + self.generator, + sample, + tgt_lang=tgt_lang, + synthesize_speech=synthesize_speech, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/modules/augmented_memory_attention.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/modules/augmented_memory_attention.py new file mode 100644 index 00000000..e7465bc8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/modules/augmented_memory_attention.py @@ -0,0 +1,488 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Tuple, List + +import torch +import torch.nn.functional as F +from fairseq.models import FairseqEncoder +from fairseq.models.speech_to_text import ( + ConvTransformerEncoder, +) +from fairseq.models.speech_to_text.utils import attention_suppression +from fairseq.models.speech_to_text.utils import ( + lengths_to_encoder_padding_mask, + segments_to_sequence, + sequence_to_segments, +) +from fairseq.modules import MultiheadAttention, TransformerEncoderLayer +from torch import nn, Tensor + +# ------------------------------------------------------------------------------ +# AugmentedMemoryConvTransformerEncoder +# ------------------------------------------------------------------------------ + + +class AugmentedMemoryConvTransformerEncoder(ConvTransformerEncoder): + def __init__(self, args): + super().__init__(args) + + args.encoder_stride = self.stride() + + self.left_context = args.left_context // args.encoder_stride + + self.right_context = args.right_context // args.encoder_stride + + self.left_context_after_stride = args.left_context // args.encoder_stride + self.right_context_after_stride = args.right_context // args.encoder_stride + + self.transformer_layers = nn.ModuleList([]) + self.transformer_layers.extend( + [ + AugmentedMemoryTransformerEncoderLayer(args) + for i in range(args.encoder_layers) + ] + ) + + def stride(self): + # Hard coded here. Should infer from convs in future + stride = 4 + return stride + + def forward(self, src_tokens, src_lengths, states=None): + """Encode input sequence. + :param torch.Tensor xs: input tensor + :param torch.Tensor masks: input mask + :return: position embedded tensor and mask + :rtype Tuple[torch.Tensor, torch.Tensor]: + """ + bsz, max_seq_len, _ = src_tokens.size() + x = ( + src_tokens.view(bsz, max_seq_len, self.in_channels, self.input_dim) + .transpose(1, 2) + .contiguous() + ) + x = self.conv(x) + bsz, _, output_seq_len, _ = x.size() + x = x.transpose(1, 2).transpose(0, 1).contiguous().view(output_seq_len, bsz, -1) + x = self.out(x) + x = self.embed_scale * x + + subsampling_factor = 1.0 * max_seq_len / output_seq_len + input_lengths = torch.max( + (src_lengths.float() / subsampling_factor).ceil().long(), + x.size(0) * src_lengths.new_ones([src_lengths.size(0)]).long(), + ) + + encoder_padding_mask, _ = lengths_to_encoder_padding_mask( + input_lengths, batch_first=True + ) + + # TODO: fix positional embedding + positions = self.embed_positions(encoder_padding_mask).transpose(0, 1) + + x += positions + x = F.dropout(x, p=self.dropout, training=self.training) + + # State to store memory banks etc. + if states is None: + states = [ + {"memory_banks": None, "encoder_states": None} + for i in range(len(self.transformer_layers)) + ] + + for i, layer in enumerate(self.transformer_layers): + # x size: + # (self.left_size + self.segment_size + self.right_size) + # / self.stride, num_heads, dim + # TODO: Consider mask here + x = layer(x, states[i]) + states[i]["encoder_states"] = x[ + self.left_context_after_stride : -self.right_context_after_stride + ] + + lengths = ( + ( + ~encoder_padding_mask[ + :, self.left_context_after_stride : -self.right_context_after_stride + ] + ) + .sum(dim=1, keepdim=True) + .long() + ) + + return states[-1]["encoder_states"], lengths, states + + +# ------------------------------------------------------------------------------ +# AugmentedMemoryTransformerEncoderLayer +# ------------------------------------------------------------------------------ +class AugmentedMemoryTransformerEncoderLayer(TransformerEncoderLayer): + def __init__(self, args): + super().__init__(args) + + self.left_context = args.left_context // args.encoder_stride + self.right_context = args.right_context // args.encoder_stride + + def forward(self, x, state): + + length, batch_size, x_dim = x.size() + + residual = x + + if self.normalize_before: + x = self.self_attn_layer_norm(x) + + # init_state + if state.get("memory_banks", None) is None: + state["memory_banks"] = [] + + # TODO reseach new sum_query method + seg_start = self.left_context + seg_end = length - self.right_context + if seg_start < seg_end: + summarization_query = torch.mean(x[seg_start:seg_end], keepdim=True, dim=0) + else: + summarization_query = x.new_zeros(1, batch_size, x_dim) + + x = torch.cat([x, summarization_query], dim=0) + + x = self.self_attn(input_and_summary=x, state=state) + + x = self.dropout_module(x) + x = residual + x + + if not self.normalize_before: + x = self.self_attn_layer_norm(x) + + residual = x + if self.normalize_before: + x = self.final_layer_norm(x) + + x = self.activation_fn(self.fc1(x)) + x = self.activation_dropout_module(x) + x = self.fc2(x) + x = self.dropout_module(x) + x = residual + x + if not self.normalize_before: + x = self.final_layer_norm(x) + + return x + + def build_self_attention(self, embed_dim, args): + return AugmentedMemoryMultiheadAttention( + embed_dim=embed_dim, + num_heads=args.encoder_attention_heads, + dropout=args.attention_dropout, + self_attention=True, + q_noise=self.quant_noise, + qn_block_size=self.quant_noise_block_size, + tanh_on_mem=True, + max_memory_size=args.max_memory_size, + ) + + +# ------------------------------------------------------------------------------ +# AugmentedMemoryMultiheadAttention +# ------------------------------------------------------------------------------ +class AugmentedMemoryMultiheadAttention(MultiheadAttention): + """ + Augmented Memory Attention from + Streaming Transformer-based Acoustic Models + Using Self-attention with Augmented Memory + https://arxiv.org/abs/2005.08042 + """ + + def __init__( + self, + embed_dim, + num_heads, + kdim=None, + vdim=None, + dropout=0.0, + bias=True, + add_bias_kv=False, + add_zero_attn=False, + self_attention=False, + encoder_decoder_attention=False, + q_noise=0.0, + qn_block_size=8, + tanh_on_mem=False, + memory_dim=None, + std_scale=0.5, # 0.5 based on https://arxiv.org/abs/2005.09137 + max_memory_size=-1, + disable_mem_on_mem_attn=True, + ): + super().__init__( + embed_dim, + num_heads, + kdim, + vdim, + dropout, + bias, + add_bias_kv, + add_zero_attn, + self_attention, + encoder_decoder_attention, + q_noise, + qn_block_size, + ) + + self.memory_dim = memory_dim if memory_dim is not None else embed_dim + self.std_scale = std_scale + self.disable_mem_on_mem_attn = disable_mem_on_mem_attn + + # This Operator was used for factorization in PySpeech + self.v2e = lambda x: x + + if tanh_on_mem: + self.squash_mem = torch.tanh + self.nonlinear_squash_mem = True + else: + self.squash_mem = lambda x: x + self.nonlinear_squash_mem = False + + self.max_memory_size = max_memory_size + + def forward(self, input_and_summary, state): + """ + input: Encoder states of current segment with left or right context, + plus one summarization query + + """ + + length, batch_size, _ = input_and_summary.shape + length = length - 1 # not include sum_query, last index + + memory = state["memory_banks"] + # TODO: positional embedding on memory + + if self.max_memory_size > -1 and len(memory) > self.max_memory_size: + # TODO: need to fix here + if self.max_memory_size == 0: + memory = memory.new_zeros(1, memory.size(1), self.memory_dim) + else: + memory = memory[-self.max_memory_size :] + + memory_and_input = torch.cat(memory + [input_and_summary[:-1]], dim=0) + input_and_sum_query = input_and_summary + + q = self.q_proj(self.v2e(input_and_sum_query)) + k = self.k_proj(self.v2e(memory_and_input)) + v = self.v_proj(self.v2e(memory_and_input)) + + q = ( + q.contiguous() + .view(-1, batch_size * self.num_heads, self.head_dim) + .transpose(0, 1) + * self.scaling + ) + k = ( + k.contiguous() + .view(-1, batch_size * self.num_heads, self.head_dim) + .transpose(0, 1) + ) + + v = ( + v.contiguous() + .view(-1, batch_size * self.num_heads, self.head_dim) + .transpose(0, 1) + ) + + attention_weights = torch.bmm(q, k.transpose(1, 2)) + + if self.disable_mem_on_mem_attn: + attention_weights = self.suppress_mem_on_mem_attention( + batch_size, self.num_heads, len(memory), attention_weights + ) + + if self.std_scale is not None: + attention_weights = attention_suppression(attention_weights, self.std_scale) + + assert list(attention_weights.shape) == [ + batch_size * self.num_heads, + length + 1, + length + len(memory), + ] + + attention_weights = torch.nn.functional.softmax( + attention_weights.float(), dim=-1 + ).type_as(attention_weights) + + attention_probs = self.dropout_module(attention_weights) + + # [T, T, B, n_head] + [T, B, n_head, d_head] -> [T, B, n_head, d_head] + attention = torch.bmm(attention_probs, v) + + assert list(attention.shape) == [ + batch_size * self.num_heads, + length + 1, + self.head_dim, + ] + + attention = ( + attention.transpose(0, 1) + .contiguous() + .view(length + 1, batch_size, self.embed_dim) + ) + + output_and_memory = self.out_proj(attention) + + next_m = output_and_memory[-1:] + next_m = self.squash_mem(next_m) + output = output_and_memory[:-1] + + state["memory_banks"].append(next_m) + + return output + + def suppress_mem_on_mem_attention( + self, B: int, num_heads: int, mem_size: int, attention_weight: Tensor + ): + """ + Arguments: + - B: batch size + - num_heads: number of attention heads + - mem_size: size of memory bank + - attention_weight: a [B*num_heads, T + 1, T + mem_size] vector + + Return: + modified attention_weight with [B*num_heads, -1, :mem_size] = -inf + """ + attention_weight[:, -1, :mem_size] = float("-inf") + return attention_weight + + +# ------------------------------------------------------------------------------ +# SequenceEncoder +# ------------------------------------------------------------------------------ +class SequenceEncoder(FairseqEncoder): + """ + SequenceEncoder encodes sequences. + + More specifically, `src_tokens` and `src_lengths` in `forward()` should + describe a batch of "complete" sequences rather than segments. + + Segment-by-segment inference can be triggered by `segment_size`: + 1) `segment_size` is None: + SequenceEncoder treats the input sequence as one single segment. + 2) `segment_size` is not None (some int instead): + SequenceEncoder does the following: + 1. breaks the input sequence into several segments + 2. inference on each segment and collect the outputs + 3. concatanete segment outputs into the output sequence. + Note that `segment_size` here shouldn't include additional left/right + contexts needed, for example if we wish to infer with LC-BLSTM where the + middle chunk size is 100 and right context is 20, `segment_size` should be + 100. + """ + + def __init__(self, args, module): + super().__init__(None) + + self.module = module + self.input_time_axis = 1 + self.output_time_axis = 0 + self.segment_size = args.segment_size + self.left_context = args.left_context + self.right_context = args.right_context + + def forward( + self, + src_tokens: Tensor, + src_lengths: Tensor, + states=None, + ): + + seg_src_tokens_lengths = sequence_to_segments( + sequence=src_tokens, + time_axis=self.input_time_axis, + lengths=src_lengths, + segment_size=self.segment_size, + extra_left_context=self.left_context, + extra_right_context=self.right_context, + ) + + seg_encoder_states_lengths: List[Tuple[Tensor, Tensor]] = [] + + for seg_src_tokens, seg_src_lengths in seg_src_tokens_lengths: + (seg_encoder_states, seg_enc_lengths, states) = self.module( + seg_src_tokens, + seg_src_lengths, + states=states, + ) + + seg_encoder_states_lengths.append((seg_encoder_states, seg_enc_lengths)) + + encoder_out, enc_lengths = segments_to_sequence( + segments=seg_encoder_states_lengths, time_axis=self.output_time_axis + ) + + encoder_padding_mask, _ = lengths_to_encoder_padding_mask( + enc_lengths, batch_first=True + ) + + if not encoder_padding_mask.any(): + encoder_padding_mask = None + + return { + "encoder_out": [encoder_out], + "encoder_padding_mask": [encoder_padding_mask], + "encoder_embedding": [], + "encoder_states": [states], + "src_tokens": [], + "src_lengths": [], + } + + def incremental_encode( + self, + seg_src_tokens: Tensor, + seg_src_lengths: Tensor, + states=None, + ): + """ + Different from forward function, this function takes segmented speech + as input, and append encoder states to previous states + """ + (seg_encoder_states, seg_enc_lengths, states) = self.module( + seg_src_tokens, + seg_src_lengths, + states=states, + ) + return seg_encoder_states, seg_enc_lengths, states + + +# ------------------------------------------------------------------------------ +# Augmented memory model decorator +# ------------------------------------------------------------------------------ +def augmented_memory(klass): + class StreamSeq2SeqModel(klass): + @staticmethod + def add_args(parser): + super(StreamSeq2SeqModel, StreamSeq2SeqModel).add_args(parser) + parser.add_argument( + "--segment-size", type=int, required=True, help="Length of the segment." + ) + parser.add_argument( + "--left-context", + type=int, + default=0, + help="Left context for the segment.", + ) + parser.add_argument( + "--right-context", + type=int, + default=0, + help="Right context for the segment.", + ) + parser.add_argument( + "--max-memory-size", + type=int, + default=-1, + help="Right context for the segment.", + ) + + StreamSeq2SeqModel.__name__ = klass.__name__ + return StreamSeq2SeqModel diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/modules/emformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/modules/emformer.py new file mode 100644 index 00000000..935d5930 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/modules/emformer.py @@ -0,0 +1,1844 @@ +#!/usr/bin/env python3 +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + + +import math +import re +from functools import partial +from typing import List, Optional, Tuple + +import torch +import torch.nn as nn +from torch import Tensor +from torch import device as Device + +from fairseq.models import FairseqEncoder +from fairseq.models.speech_to_text.utils import ( + NoOp, + attention_suppression, + layer_norm_backward_hook, + lengths_to_padding_mask, + segments_to_sequence, +) + +try: + import torch.ao.quantization as quantization + from torch.ao.quantization.qconfig import ( + default_dynamic_qconfig, + per_channel_dynamic_qconfig, + ) +except ImportError: + import torch.quantization as quantization + from torch.quantization.qconfig import ( + default_dynamic_qconfig, + per_channel_dynamic_qconfig, + ) + + +class RelativePositionEmbedding(nn.Module): + """ + Implementation according to https://arxiv.org/abs/1803.02155 + """ + + def __init__(self, head_dim, max_position, norm_init=True): + super().__init__() + self.head_dim = head_dim + self.max_position = max_position + self.embeddings = nn.Parameter(torch.Tensor(max_position * 2 + 1, head_dim)) + if norm_init: + nn.init.xavier_normal_(self.embeddings) + else: + nn.init.xavier_uniform_(self.embeddings) + + def forward(self, input: Tensor): + output = nn.functional.embedding(input.long(), self.embeddings) + return output + + +class Fp32LayerNorm(nn.Module): + def __init__( + self, + input_dim, + clamp_grad=True, + max_grad_value=256, + eps=1e-5, + elementwise_affine=True, + ): + super().__init__() + self.torch_module = torch.nn.LayerNorm( + input_dim, eps=eps, elementwise_affine=elementwise_affine + ) + if clamp_grad: + hook = partial(layer_norm_backward_hook, clamp_value=max_grad_value) + self.torch_module.register_backward_hook(hook) + + def forward(self, input): + output = torch.nn.functional.layer_norm( + input.float(), + self.torch_module.normalized_shape, + self.torch_module.weight.float() + if self.torch_module.weight is not None + else None, + self.torch_module.bias.float() + if self.torch_module.bias is not None + else None, + self.torch_module.eps, + ).type_as(input) + return output + + +# ------------------------------------------------------------------------------ +# PositionwiseFF +# ------------------------------------------------------------------------------ + + +class PositionwiseFF(nn.Module): + """ + FFN layer in transformer. + + Args: + input_dim: input embedding dimension + ffn_dim: FFN layer inner dimension + dropout_on_fc1: dropout for first linear layer + dropout_on_fc2: dropout fr second linear layer + activation_fn: activation function used after first linear layer. \ + Only relu or gelu is supported. + + """ + + def __init__( + self, input_dim, ffn_dim, dropout_on_fc1, dropout_on_fc2, activation_fn + ): + super(PositionwiseFF, self).__init__() + + self.input_dim = input_dim + self.ffn_dim = ffn_dim + if activation_fn == "relu": + ac = nn.ReLU() + elif activation_fn == "gelu": + ac = nn.GELU() + else: + raise ValueError("Unsupported activation_fn = ({})".format(activation_fn)) + + # fc1 -> ac -> dropout -> fc2 -> dropout + self.module = nn.Sequential( + nn.Linear(input_dim, ffn_dim), + ac, + nn.Dropout(dropout_on_fc1), + nn.Linear(ffn_dim, input_dim), + nn.Dropout(dropout_on_fc2), + ) + + self.layer_norm = Fp32LayerNorm(input_dim) + + def forward(self, input): + module_out = self.module(self.layer_norm(input)) + output = module_out + input + + return output + + def quantize_(self, params=None): + if params and "per_channel" in params and params["per_channel"]: + qconfig = per_channel_dynamic_qconfig + else: + qconfig = default_dynamic_qconfig + quantization.quantize_dynamic( + self, {torch.nn.Linear: qconfig}, dtype=torch.qint8, inplace=True + ) + return self + + +# ------------------------------------------------------------------------------ +# SummarizationLayer +# ------------------------------------------------------------------------------ + + +class SummarizationLayer(nn.Module): + def __init__(self, method, segment_size, embedding_dim): + super(SummarizationLayer, self).__init__() + self.segment_size = segment_size + self.embedding_dim = embedding_dim + nonlin_match = re.match(r"nonlinear\((?P[a-z]+),(?P[0-9]+)\)", method) + self.method = method + if method == "mean": + self.module = nn.AvgPool1d( + kernel_size=segment_size, + stride=segment_size, + ceil_mode=True, + ) + elif method == "max": + self.module = nn.MaxPool1d( + kernel_size=segment_size, + stride=segment_size, + ceil_mode=True, + ) + elif method == "linear": + self.module = nn.Linear(segment_size, 1) + elif nonlin_match: + nonlin_args = nonlin_match.groupdict() + act_type = nonlin_args["act"] + hid_dim = int(nonlin_args["dim"]) + if act_type == "relu": + act = nn.ReLU() + elif act_type == "gelu": + act = nn.GELU() + else: + raise ValueError("Unsupported activation_fn = ({})".format(act_type)) + self.module = nn.Sequential( + nn.Linear(segment_size, hid_dim), + act, + nn.Linear(hid_dim, 1), + ) + else: + raise ValueError("Unsupported summarization method = ({})".format(method)) + + def forward(self, input): + # T, B, D -> B, D, T + input = input.permute(1, 2, 0) + + if self.method == "mean" or self.method == "max": + output = self.module(input) + output = output.permute(2, 0, 1) + return output + + full_seg_length = input.size(2) // self.segment_size * self.segment_size + if full_seg_length > 0: + # at least one seg is full + B = input.size(0) + D = input.size(1) + input_todo = ( + input[:, :, :full_seg_length] + .contiguous() + .view(B, -1, self.segment_size) + ) + output = self.module(input_todo) + output = output.view(B, D, -1) + else: + output = input.new_zeros(input.size(0), input.size(1), 0) + left = input.size(2) - full_seg_length + if left > 0: + # when last seg is not full, use zeros as last memory placeholder + zeros = input.new_zeros(input.size(0), input.size(1), 1) + output = torch.cat([output, zeros], dim=2) + output = output.permute(2, 0, 1) + return output + + +# ------------------------------------------------------------------------------ +# NoSegAugmentedMemoryMultiheadAttentionBmm +# ------------------------------------------------------------------------------ + + +class NoSegAugmentedMemoryMultiheadAttentionBmm(nn.Module): + """ + Whole utterance augmented memory multihead attention using BMM. + + Different with previous augmented memory multihead attention where + the utterance is chunked into segments. Here we use attention mask + achieve so. The input embedding [right_context, utterance, summary] + is a concatenation of right context, utterance and summary. + + Right context block is the concatenation of all the right context for + each segments. [right_context_0, right_context_1, ..., right_context_n] + For example, if we have utterance = [v0, v1, v2, ...., v20]. segment + size 8, right_context size 4. Then the right context blocks = + [v8, v9, v10, v11, v16, v17, v18, v19, 0, 0, 0, 0], where v8, v9, v10, + and v11 are the right context for first segment. v16, v17, v18 and v19 + are the right context for second segment. 0, 0, 0 and 0 are right context + for the last segment. + + utterance is corresponding to input embedding sequence + + summary is concatenation of average of each segments. [summary_0, + summary_1, ..., ]. + + In augmented memory multihead attention, the query is [right_context, + utterance, summary], key is [memory, right_context, utterance]. Different + with AugmentedMemoryMultiheadAttentionBmm, memory here is passed from + previous attention layer. For the first attention layer, memory is average + of each segment. + + Memory is a concatenation of memory from each segments in previous attention + layer. For example, current layer is i, then memory is [m_0, m_1, ..., m_n]. + Each m_k is the output from seg_k in layer i-1. + + args: + input_dim: input embedding dimension + num_heads: number of heads in multihead self-attention + dropout: attention dropout + std_scale: if std_scale is not None. The weak attention suppression is + turned on. For std_scale = 0.5, all the attention smaller than + mean + 0.5 * std will be suppressed. + scaled_init: whether to use scaled init for linear weight + tanh_on_mem: whether to use tanh on memory output + use_mem: whether to use memory or not. When max_memory_size is 0, then + we don't have memory anymore. + layer_index: current self-attention layer index that is used in depth + initialization + max_relative_position: max relative position used in relative position + embedding + rpe_old_option: To be compatible with previous model. The previous model + was trained with attention += attention + rpe. The correct equation + should be attention = attention + rpe + + """ + + def __init__( + self, + input_dim, + num_heads, + dropout=0.0, + std_scale=None, + scaled_init=False, + tanh_on_mem=False, + use_mem=True, + mini_batches=False, + negative_inf="-inf", + layer_index=-1, + max_relative_position=0, + rpe_old_option=True, + ): + if input_dim % num_heads: + raise ValueError( + "input_dim ({}) must be divisible by num_heads ({})".format( + input_dim, num_heads + ) + ) + + super().__init__() + + embed_dim = input_dim + self.e2h_kv = torch.nn.Linear(input_dim, 2 * input_dim, bias=True) + self.e2h_q = torch.nn.Linear(input_dim, input_dim, bias=True) + self.rpe_old_option = rpe_old_option + if max_relative_position > 0: + self.use_rpe = True + self.rpe_k = RelativePositionEmbedding( + head_dim=input_dim // num_heads, + max_position=max_relative_position, + ) + self.rpe_v = RelativePositionEmbedding( + head_dim=input_dim // num_heads, + max_position=max_relative_position, + ) + else: + self.use_rpe = False + self.rpe_k = None + self.rpe_v = None + if scaled_init: + if layer_index == -1: + gain = 1.0 / math.sqrt(2) + else: + # https://arxiv.org/abs/2005.09684 depthwise initialization + # stablize the training greatly. Use depthwise initialization to + # replace incremental loss. + gain = 1.0 / math.sqrt(layer_index + 1) + torch.nn.init.xavier_uniform_(self.e2h_kv.weight, gain=gain) + torch.nn.init.xavier_uniform_(self.e2h_q.weight, gain=gain) + + self.out_proj = torch.nn.Linear(embed_dim, embed_dim, bias=True) + + self.embed_dim = embed_dim + self.num_heads = num_heads + self.dropout = dropout + + self.head_dim = embed_dim // num_heads + self.scaling = self.head_dim**-0.5 + + self.std_scale = std_scale + self.use_mem = use_mem + self.mini_batches = mini_batches + self.negative_inf = negative_inf + + if tanh_on_mem: + self.squash_mem = torch.tanh + self.nonlinear_squash_mem = True + else: + self.squash_mem = NoOp() + self.nonlinear_squash_mem = False + + def prepare_qkv( + self, + input: Tensor, + mems: Tensor, + lengths: Tensor, + summary_length: int, + lc_length: int, + ): + # T: right_context length + utterance_length + summary_length + T, B, D = input.shape + mem_length = mems.size(0) + utterance_length = torch.max(lengths) + + right_context_blocks_length = T - utterance_length - summary_length + rc_block = input[:right_context_blocks_length, :, :] + utterance_block = input[right_context_blocks_length : T - summary_length, :, :] + + if B == 1: + padding_mask = None + else: + klengths = lengths + mem_length + right_context_blocks_length + lc_length + padding_mask = lengths_to_padding_mask(lengths=klengths) + + mem_rc_input = torch.cat([mems, rc_block, utterance_block], dim=0) + + # In training lc_length = 0 + key_length = mem_rc_input.size(0) + lc_length + rc_input_sum = input + q = self.e2h_q(rc_input_sum) + kv = self.e2h_kv(mem_rc_input) + k, v = kv.chunk(chunks=2, dim=2) + result_qkv = (q, k, v) + input_shape = (T, B, D) + result_lengths_info = ( + mem_length, + utterance_length, + right_context_blocks_length, + key_length, + ) + if padding_mask is not None: + assert padding_mask.size(0) == B + assert padding_mask.size(1) == key_length + + return result_qkv, input_shape, result_lengths_info, padding_mask + + def prepare_attention_weights( + self, + q: Tensor, + new_k: Tensor, + new_v: Tensor, + input_shape: Tuple[int, int, int], + rpe: Optional[Tensor], + ) -> Tuple[Tensor, Tensor, Tensor]: + T, B, D = input_shape + q = ( + q.contiguous().view(-1, B * self.num_heads, self.head_dim).transpose(0, 1) + * self.scaling + ) + + k = ( + new_k.contiguous() + .view(-1, B * self.num_heads, self.head_dim) + .transpose(0, 1) + ) + + v = ( + new_v.contiguous() + .view(-1, B * self.num_heads, self.head_dim) + .transpose(0, 1) + ) + + attention_weights = torch.bmm(q, k.transpose(1, 2)) + if self.use_rpe and rpe is not None and self.rpe_v is not None: + r_k = self.rpe_k(rpe) + # [q, B*h, d] * [q, k, d] -> [B*h, q, k] + attention_weights_rpe = torch.matmul( + q.transpose(0, 1), r_k.transpose(1, 2) + ).transpose(0, 1) + attention_weights = attention_weights + attention_weights_rpe + attention_weights_float = attention_weights.float() + + return attention_weights, attention_weights_float, v + + def prepare_attention_output( + self, + attention_weights: Tensor, + attention_weights_float: Tensor, + v: Tensor, + input_shape: Tuple[int, int, int], + key_length: int, + padding_mask: Optional[Tensor], + rpe: Optional[Tensor], + ) -> Tensor: + T, B, D = input_shape + if padding_mask is not None: + attention_weights_float = attention_weights_float.view( + B, self.num_heads, T, key_length + ) + attention_weights_float = attention_weights_float.masked_fill( + padding_mask.unsqueeze(1).unsqueeze(2).to(torch.bool), float("-inf") + ) + attention_weights_float = attention_weights_float.view( + B * self.num_heads, T, key_length + ) + + if self.std_scale is not None: + attention_weights_float = attention_suppression( + attention_weights_float, self.std_scale + ) + + attention_weights_float = torch.nn.functional.softmax( + attention_weights_float, dim=-1 + ) + attention_weights = attention_weights_float.type_as(attention_weights) + + attention_probs = torch.nn.functional.dropout( + attention_weights, p=self.dropout, training=self.training + ) + + # [T, key_length, B, n_head]+ [key_length, B, n_head, d_head] + # -> [T, B, n_head, d_head] + attention = torch.bmm(attention_probs, v) + if self.use_rpe and rpe is not None and self.rpe_v is not None: + r_v = self.rpe_v(rpe) + attention_rpe = torch.matmul( + attention_probs.transpose(0, 1), r_v + ).transpose(0, 1) + + if self.rpe_old_option: + attention += attention + attention_rpe + else: + attention = attention + attention_rpe + + assert list(attention.shape) == [B * self.num_heads, T, self.head_dim] + + attention = attention.transpose(0, 1).contiguous().view(T, B, self.embed_dim) + + rc_output_memory = self.out_proj(attention) + return rc_output_memory + + @torch.jit.unused + def forward( + self, + input: Tensor, + lengths: Tensor, + mems: Tensor, + attention_mask: Tensor, + pre_mems: Optional[Tensor] = None, + left_context_key: Optional[Tensor] = None, + left_context_val: Optional[Tensor] = None, + rpe: Optional[Tensor] = None, + ) -> Tuple[Tensor, Tensor, Tensor, Tensor]: + """ + forward function for NoSegAugmentedMemoryMultiheadAttentionBmm in training. + + args: + input: formed in the following way + [right_context_0, right_contex_1, ..., seg_0, seg_1, + ..., summary_0, summary_1,..] + lengths: the length of query which is [seg_0, seg_1, ....] + mems: [mem_0, mem_1, ...]. + attention_mask: attention mask for query = [right_context, query, summary] + key = [mem, right_context, query]. This is only used for traing. + + """ + if self.use_mem: + mem_length = mems.size(0) + summary_length = mem_length + 1 + if pre_mems is not None: + mems = torch.cat([pre_mems, mems], dim=0) + else: + mem_length = 0 + summary_length = 0 + + # In training, lc_length = 0 + if left_context_key is not None: + lc_length = left_context_key.size(0) + else: + lc_length = 0 + results = self.prepare_qkv( + input=input, + mems=mems, + lengths=lengths, + summary_length=summary_length, + lc_length=lc_length, + ) + result_qkv, input_shape, result_lengths_info, padding_mask = results + q, k, v = result_qkv + ( + mem_length, + utterance_length, + right_context_blocks_length, + key_length, + ) = result_lengths_info + + if left_context_key is not None: + # add the cache key and value + new_k = torch.cat( + [ + k[: mem_length + right_context_blocks_length, :, :], + left_context_key, + k[-utterance_length:, :, :], + ], + dim=0, + ) + new_v = torch.cat( + [ + v[: mem_length + right_context_blocks_length, :, :], + left_context_val, + v[-utterance_length:, :, :], + ], + dim=0, + ) + next_k = new_k[mem_length + right_context_blocks_length :, :, :] + next_v = new_v[mem_length + right_context_blocks_length :, :, :] + else: + new_k = k + new_v = v + next_k = None + next_v = None + + attention_weights, attention_weights_float, v = self.prepare_attention_weights( + q=q, + new_k=new_k, + new_v=new_v, + input_shape=input_shape, + rpe=rpe, + ) + + # mask attention + attention_mask = attention_mask.unsqueeze(0) + attention_weights_float = attention_weights_float.masked_fill( + attention_mask, float(self.negative_inf) + ) + + rc_output_memory = self.prepare_attention_output( + attention_weights=attention_weights, + attention_weights_float=attention_weights_float, + v=v, + input_shape=input_shape, + key_length=key_length, + padding_mask=padding_mask, + rpe=rpe, + ) + + if self.use_mem: + # next_m length equals to summary length - 1 + # last memory is ignored + if self.mini_batches: + next_m = rc_output_memory[-summary_length:] + else: + next_m = rc_output_memory[-summary_length:-1] + + next_m = self.squash_mem(next_m) + # rc and output + rc_output = rc_output_memory[:-summary_length] + if not self.nonlinear_squash_mem: + next_m = torch.clamp(next_m, min=-10, max=10) + else: + next_m = mems + rc_output = rc_output_memory + + return rc_output, next_m, next_k, next_v + + @torch.jit.export + def forward_jit( + self, + input: Tensor, + lengths: Tensor, + mems: Tensor, + left_context_key: Tensor, + left_context_val: Tensor, + rpe: Optional[Tensor], + ) -> Tuple[Tensor, Tensor, Tensor, Tensor]: + """ + forward function for NoSegAugmentedMemoryMultiheadAttentionBmm in decoding. + + args: + input: formed in the following way + [right_context_0, right_contex_1, ..., seg_0, seg_1, + ..., summary_0, summary_1,..] + lengths: the length of query which is [seg_0, seg_1, ....] + mems: [mem_0, mem_1, ...]. + left_context_key: left_context for key part. This is only used for online + decoding. In training, this is empty tensor + left_context_val: left_context for value part. This is only used for online + decoding. In training, this is empty tensor + + """ + lc_length = left_context_key.size(0) + + # In decoding, summary_length = 1 or 0 + if self.use_mem: + summary_length = 1 + else: + summary_length = 0 + + results = self.prepare_qkv( + input=input, + mems=mems, + lengths=lengths, + summary_length=summary_length, + lc_length=lc_length, + ) + result_qkv, input_shape, result_lengths_info, padding_mask = results + q, k, v = result_qkv + ( + mem_length, + utterance_length, + right_context_blocks_length, + key_length, + ) = result_lengths_info + + # add the cache key and value + new_k = torch.cat( + [ + k[: mem_length + right_context_blocks_length, :, :], + left_context_key, + k[-utterance_length:, :, :], + ], + dim=0, + ) + new_v = torch.cat( + [ + v[: mem_length + right_context_blocks_length, :, :], + left_context_val, + v[-utterance_length:, :, :], + ], + dim=0, + ) + next_k = new_k[mem_length + right_context_blocks_length :, :, :] + next_v = new_v[mem_length + right_context_blocks_length :, :, :] + + attention_weights, attention_weights_float, v = self.prepare_attention_weights( + q=q, + new_k=new_k, + new_v=new_v, + input_shape=input_shape, + rpe=rpe, + ) + # In online decoding, we don't have attention mask. But we still need + # to disable the attention from summary query to memory + attention_weights_float[:, -1, :mem_length] = float(self.negative_inf) + rc_output_memory = self.prepare_attention_output( + attention_weights=attention_weights, + attention_weights_float=attention_weights_float, + v=v, + input_shape=input_shape, + key_length=key_length, + padding_mask=padding_mask, + rpe=rpe, + ) + + # In decoding, summary length is 1 + if self.use_mem: + next_m = rc_output_memory[-1:] + next_m = self.squash_mem(next_m) + # rc and output + rc_output = rc_output_memory[:-1] + if not self.nonlinear_squash_mem: + next_m = torch.clamp(next_m, min=-10, max=10) + else: + rc_output = rc_output_memory + # empty tensor as input mems + next_m = mems + + return rc_output, next_m, next_k, next_v + + def quantize_(self, params=None): + if params and "per_channel" in params and params["per_channel"]: + qconfig = per_channel_dynamic_qconfig + else: + qconfig = default_dynamic_qconfig + quantization.quantize_dynamic( + self, {torch.nn.Linear: qconfig}, dtype=torch.qint8, inplace=True + ) + return self + + +class NoSegAugmentedMemoryTransformer(nn.Module): + """ + Whole utterance augmented memory transformer. + + This is not pyspeech nn layer. It is used as a module in a master layer where + multiple transformers is used. + """ + + def __init__( + self, + input_dim, + num_heads, + ffn_dim, + dropout_in_attn=0.0, + dropout_on_attn=None, + dropout_on_fc1=None, + dropout_on_fc2=None, + activation_fn="relu", + tanh_on_mem=False, + std_scale=None, + scaled_init=False, + segment_size=128, + use_mem=True, + mini_batches=False, + negative_inf="-inf", + layer_index=-1, + summarization_method="mean", + max_relative_position=0, + rpe_old_option=True, + ): + super(NoSegAugmentedMemoryTransformer, self).__init__() + + self.attention = NoSegAugmentedMemoryMultiheadAttentionBmm( + input_dim=input_dim, + num_heads=num_heads, + dropout=dropout_in_attn, + scaled_init=scaled_init, + tanh_on_mem=tanh_on_mem, + std_scale=std_scale, + use_mem=use_mem, + mini_batches=mini_batches, + negative_inf=negative_inf, + layer_index=layer_index, + max_relative_position=max_relative_position, + ) + self.dropout = nn.Dropout(dropout_on_attn) + self.pos_ff = PositionwiseFF( + input_dim=input_dim, + ffn_dim=ffn_dim, + dropout_on_fc1=dropout_on_fc1, + dropout_on_fc2=dropout_on_fc2, + activation_fn=activation_fn, + ) + self.layer_norm_pre = Fp32LayerNorm(input_dim) + self.layer_norm = Fp32LayerNorm(input_dim) + self.segment_size = segment_size + self.use_mem = use_mem + + self.memory_op = SummarizationLayer( + summarization_method, segment_size, input_dim + ) + + def set_mini_batches(self, mini_batches): + self.attention.mini_batches = mini_batches + + def gen_summary_queries(self, input): + sum_input = self.memory_op(input) + return sum_input + + def pre_attention_ops(self, input, right_context_blocks): + rc_length = right_context_blocks.size(0) + input_length = input.size(0) + + rc_and_input = torch.cat([right_context_blocks, input], dim=0) + residual_input = rc_and_input + rc_and_input = self.layer_norm_pre(rc_and_input) + + query_input = rc_and_input[-input_length:, :, :] + return rc_length, input_length, residual_input, query_input, rc_and_input + + def after_attention_ops(self, attention_output, residual_input): + output = self.dropout(attention_output) + output = output + residual_input + output = self.pos_ff(output) + output = self.layer_norm(output) + return output + + @torch.jit.export + def forward_jit( + self, + input: Tensor, + lengths: Tensor, + mems: Tensor, + left_context_key: Tensor, + left_context_val: Tensor, + right_context_blocks: Tensor, + rpe: Optional[Tensor], + ) -> Tuple[Tensor, Tensor, Tensor, Tensor, Tensor]: + + results = self.pre_attention_ops(input, right_context_blocks) + rc_length, input_length, residual_input, query_input, rc_and_input = results + + # In online decoding, the summary query size is always 1 or 0 + if self.use_mem: + summary_query = self.gen_summary_queries(query_input) + summary_query = summary_query[0:1, :, :] + rc_qu_su = torch.cat([rc_and_input, summary_query], dim=0) + else: + rc_qu_su = rc_and_input + + rc_output, next_m, next_k, next_v = self.attention.forward_jit( + input=rc_qu_su, + lengths=lengths, + mems=mems, + left_context_key=left_context_key, + left_context_val=left_context_val, + rpe=rpe, + ) + rc_output = self.after_attention_ops(rc_output, residual_input) + results = ( + rc_output[-input_length:, :, :], + next_m, + rc_output[0:rc_length, :, :], + next_k, + next_v, + ) + return results + + @torch.jit.unused + def forward( + self, + input, + lengths, + mems, + right_context_blocks, + attention_mask, + pre_mems, + left_context_key, + left_context_val, + rpe, + ): + + results = self.pre_attention_ops(input, right_context_blocks) + rc_length, input_length, residual_input, query_input, rc_and_input = results + if self.use_mem: + summary_query = self.gen_summary_queries(query_input) + rc_qu_su = torch.cat([rc_and_input, summary_query], dim=0) + else: + rc_qu_su = rc_and_input + + rc_output, next_m, next_k, next_v = self.attention( + input=rc_qu_su, + lengths=lengths, + mems=mems, + attention_mask=attention_mask, + pre_mems=pre_mems, + left_context_key=left_context_key, + left_context_val=left_context_val, + rpe=rpe, + ) + + # [TODO] Note memory did not go through pos_ff. What happen if we pass + # memory through the pos_ff as well? + rc_output = self.after_attention_ops(rc_output, residual_input) + results = ( + rc_output[-input_length:, :, :], + next_m, + rc_output[0:rc_length, :, :], + next_k, + next_v, + ) + + return results + + +class NoSegAugmentedMemoryTransformerEncoderLayer(FairseqEncoder): + """ + Whole utterance augmented memory transformer encoder layer. This is a master layer + where we can define multiple augmented memory transformers. There are two reasons + to setup the master layer. + 1. We only need to define once about the attention mask. All the layers in the master + layer share the same mask. + 2. pyspeech nn layer has special input and output format. Defining one master layer is + easier to passing memory between different layes inside the master layer + + args: + input_dim: input embedding dimension + num_heads: number of heads in multihead self-attention + ffn_dim: ffn dimension in FFN layer + num_layers: number of augmented memory transformer layers + dropout_in_attn: dropout used in multi-head self-attention + dropout_on_attn: dropout used for output from te multihead self-attention + dropout_on_fc1: dropout used in FFN layer for the first linear layer + dropout_on_fc2: dropout used in FFN layer for the second linear layer + segment_size: segment size for each segment + context_config: (left_context_size, right_context_size) defines the surround context size + for each segment + max_memory_size: maximum memory size used for each segment + scaled_init: whether use scaled init for weight initialization in attention layer + std_scale: if std_scale is not None. The weak attention suppression is + turned on. For std_scale = 0.5, all the attention smaller than + mean + 0.5 * std will be suppressed. + activation_fn: activation function used in FFN layer. [ReLU, GELU] supported + tanh_on_mem: whether use tanh on memory + mini_batches: use mini-btach training + negative_inf: the negative infinity value used in attention masking. default is "-inf". + For some situation, e.g. LM. it is better to use "-1e8" to avoid nan issue. + summarization_method: method to generate segment summrization embedding + max_relative_position: max relatie position for relative position embedding + rpe_old_option: To be compatible with previous model. The previous model + was trained with attention += attention + rpe. The correct equation + should be attention = attention + rpe + [TODO]: remove the rpe_old_option by the end of 2021 Q1. + + """ + + def __init__( + self, + input_dim, + num_heads, + ffn_dim, + num_layers=1, + dropout_in_attn=0.0, + dropout_on_attn=0.0, + dropout_on_fc1=0.0, + dropout_on_fc2=0.0, + segment_size=128, + context_config=(0, 0), + max_memory_size=0, + scaled_init=True, + std_scale=None, + activation_fn="relu", + tanh_on_mem=False, + mini_batches=False, + negative_inf="-inf", + deep_init=True, + summarization_method="mean", + max_relative_position=0, + rpe_old_option=True, + ): + super().__init__(None) + if input_dim % num_heads: + raise ValueError( + "input_dim ({}) must be divisible by num_heads ({})".format( + input_dim, num_heads + ) + ) + + # we used to support growing memory size. However, it will cause + # cross stream batching failure. Now we need to have exact max memory size + if max_memory_size < 0: + raise ValueError("max_memory_size must be >= 0") + + # Only assign right_context. In decoding, left context will be cached. + # No need to let the online decoder to re-assign the left context + self.left_context, self.right_context = context_config + self.segment_size = segment_size + self.memory_dim = input_dim + self.max_memory_size = max_memory_size + self.mini_batches = mini_batches + if self.max_memory_size != 0: + self.use_mem = True + else: + self.use_mem = False + + self.memory_op = SummarizationLayer( + summarization_method, segment_size, input_dim + ) + + self.layers = torch.nn.ModuleList() + self.num_layers = num_layers + self.max_relative_position = max_relative_position + if self.max_relative_position > 0: + self.use_rpe = True + else: + self.use_rpe = False + for i in range(self.num_layers): + if deep_init: + layer_index = i + else: + layer_index = -1 + + self.layers.append( + NoSegAugmentedMemoryTransformer( + num_heads=num_heads, + input_dim=input_dim, + ffn_dim=ffn_dim, + dropout_in_attn=dropout_in_attn, + dropout_on_attn=dropout_on_attn, + dropout_on_fc1=dropout_on_fc1, + dropout_on_fc2=dropout_on_fc2, + segment_size=segment_size, + std_scale=std_scale, + activation_fn=activation_fn, + tanh_on_mem=tanh_on_mem, + scaled_init=scaled_init, + use_mem=self.use_mem, + mini_batches=mini_batches, + negative_inf=negative_inf, + layer_index=layer_index, + summarization_method=summarization_method, + max_relative_position=max_relative_position, + rpe_old_option=rpe_old_option, + ) + ) + + def set_mini_batches(self, mini_batches): + # handy function only used for unit test + self.mini_batches = mini_batches + for layer in self.layers: + layer.set_mini_batches(mini_batches) + + def _get_relative_position( + self, + input: Tensor, + max_relative_position: int, + left_context_length: int, + past_length: int, + is_decoding: bool, + ): + # For training, we copy the right context to the start of the utterance + # First dimension in distance is corresponding to query. + # [right context, utterance, summary vector] + # Second dimension in distance is corresponding to key. + # [Memory bank, right context, utterance] + # For summary vector in query part, the distance with + # all other position is 2*max_position. For memory bank in key, + # the distance with all other positions is 0. + + T, B, D = input.shape + num_segs = math.ceil((T - self.right_context) / self.segment_size) + + # utterance + u_st = past_length * self.segment_size + u_ed = u_st + T + utterance_ranges = torch.arange(u_st, u_ed - self.right_context) + + # left context. Only in minibatch or decoding + left_context_ranges = torch.arange(u_st - left_context_length, u_st) + + # Right context block + # right context + utterance + right_context_blocks = [] + for i in range(0, num_segs - 1): + st = (i + 1) * self.segment_size + u_st + ed = st + self.right_context + assert ed < u_ed + temp = torch.arange(st, ed) + right_context_blocks.append(temp) + right_context_blocks.append(torch.arange(u_ed - self.right_context, u_ed)) + right_context_ranges = torch.cat(right_context_blocks) + + if self.use_mem: + # Memory bank + # The position for memory -n, .., -1 + if is_decoding: + memory_size = min(past_length, self.max_memory_size) + else: + memory_size = num_segs + past_length - 1 + memory_bank_ranges = torch.arange( + -max_relative_position - 1, -max_relative_position - 1 - memory_size, -1 + ) + + # summary vector + # The position for summary vector as the T+max_relative_position+1. + # After the clamping, the relative position is max_relative_position + summary_pos_st = u_ed + max_relative_position + 1 + summary_vector_ranges = torch.arange( + summary_pos_st, summary_pos_st + num_segs + ) + + key_ranges = torch.cat( + [ + memory_bank_ranges, + right_context_ranges, + left_context_ranges, + utterance_ranges, + ] + ) + + query_ranges = torch.cat( + [right_context_ranges, utterance_ranges, summary_vector_ranges] + ) + else: + key_ranges = torch.cat( + [right_context_ranges, left_context_ranges, utterance_ranges] + ) + + query_ranges = torch.cat([right_context_ranges, utterance_ranges]) + + distance = key_ranges[None, :] - query_ranges[:, None] + distance_clamp = ( + torch.clamp(distance, -max_relative_position, max_relative_position) + + max_relative_position + ) + distance_clamp = distance_clamp.to(input.device).long().detach() + return distance_clamp + + def _get_attention_mask(self, input, past_length=0, left_context_cache=0): + # attention mask for each query contains three parts: + # 1. memory part + # 2. left_context + segment + # 3. right_context_block + # so for each segment and its correspoinding right context block, + # the attention matrix is formed by 9 parts: + # [0, m, 0, 0, right_context, 0, 0, seg, 0] + # [before memory, memory, after memory, before right context, right_context, + # after right context, before seg, seg, after seg] + # + # Query is formed in the way as [right_context_blocks, utterance, summary] + # + # Note: put m and right_context before segment is convenient + # for padding_mask operation. + # Key lengths = m_length + right_context_block_length + lengths + utterance_length, batch_size, _ = input.shape + summary_length = math.ceil(utterance_length / self.segment_size) + num_segs = summary_length + rc_length = self.right_context * num_segs + rc = self.right_context + lc = self.left_context + + # using mini-batches, there is left context cache available for current + # sequence. + lcc = left_context_cache + + # max_memory_size is 0 then we don't have memory and summary + # past_length is the memory carry from previous sequence + if self.use_mem: + mem_length = num_segs - 1 + past_length + else: + mem_length = 0 + rc_mask = [] + query_mask = [] + summary_mask = [] + for j in range(0, num_segs): + ssize = min(self.segment_size, utterance_length - j * self.segment_size) + + rc_size = rc + rc_mat = [] + q_mat = [] + s_mat = [] + m_start = max(j + past_length - self.max_memory_size, 0) + + # max_memory_size is 0, then we don't use memory + if self.use_mem: + # part 0: before memory + rc_mat.append(input.new_zeros(rc_size, m_start)) + q_mat.append(input.new_zeros(ssize, m_start)) + s_mat.append(input.new_zeros(1, m_start)) + + # part 1: memory + col_1 = j + past_length - m_start + rc_mat.append(torch.ones(rc_size, col_1, device=input.device)) + q_mat.append(torch.ones(ssize, col_1, device=input.device)) + # based on D22875746, disable summary query attention + # on memeory is better for long form utterance + s_mat.append(input.new_zeros(1, col_1)) + + # part 2: after memory + col_2 = mem_length - (j + past_length) + rc_mat.append(input.new_zeros(rc_size, col_2)) + q_mat.append(input.new_zeros(ssize, col_2)) + s_mat.append(input.new_zeros(1, col_2)) + + # part 3: before right context + rc_start = j * rc + rc_mat.append(input.new_zeros(rc_size, rc_start)) + q_mat.append(input.new_zeros(ssize, rc_start)) + s_mat.append(input.new_zeros(1, rc_start)) + + # part 4: right context + rc_end = rc_start + rc + col_4 = rc + rc_mat.append(torch.ones(rc_size, col_4, device=input.device)) + q_mat.append(torch.ones(ssize, col_4, device=input.device)) + s_mat.append(torch.ones(1, col_4, device=input.device)) + + # part 5: after right context + col_5 = rc_length - rc_end + rc_mat.append(input.new_zeros(rc_size, col_5)) + q_mat.append(input.new_zeros(ssize, col_5)) + s_mat.append(input.new_zeros(1, col_5)) + + # part 6: before query segment + seg_start = max(j * self.segment_size + lcc - lc, 0) + rc_mat.append(input.new_zeros(rc_size, seg_start)) + q_mat.append(input.new_zeros(ssize, seg_start)) + s_mat.append(input.new_zeros(1, seg_start)) + + # part 7: query segment + # note: right context is put in right context block + # here we only need to consider about left context + seg_end = min((j + 1) * self.segment_size + lcc, utterance_length + lcc) + col_7 = seg_end - seg_start + rc_mat.append(torch.ones(rc_size, col_7, device=input.device)) + q_mat.append(torch.ones(ssize, col_7, device=input.device)) + s_mat.append(torch.ones(1, col_7, device=input.device)) + + # part 8: after query segment + col_8 = utterance_length + lcc - seg_end + rc_mat.append(input.new_zeros(rc_size, col_8)) + q_mat.append(input.new_zeros(ssize, col_8)) + s_mat.append(input.new_zeros(1, col_8)) + + rc_mask.append(torch.cat(rc_mat, dim=1)) + query_mask.append(torch.cat(q_mat, dim=1)) + summary_mask.append(torch.cat(s_mat, dim=1)) + + # no memory, then we don't need summary either + if self.use_mem: + attention_mask = ( + 1 + - torch.cat( + [ + torch.cat(rc_mask, dim=0), + torch.cat(query_mask, dim=0), + torch.cat(summary_mask, dim=0), + ], + dim=0, + ) + ).to(torch.bool) + else: + attention_mask = ( + 1 + - torch.cat( + [torch.cat(rc_mask, dim=0), torch.cat(query_mask, dim=0)], dim=0 + ) + ).to(torch.bool) + + return attention_mask + + @torch.jit.export + def init_state( + self, batch_size: int, device: Optional[Device] = None + ) -> List[Tensor]: + empty_memory = torch.zeros( + self.num_layers, + self.max_memory_size, + batch_size, + self.memory_dim, + device=device, + ) + left_context_key = torch.zeros( + self.num_layers, + self.left_context, + batch_size, + self.memory_dim, + device=device, + ) + left_context_val = torch.zeros( + self.num_layers, + self.left_context, + batch_size, + self.memory_dim, + device=device, + ) + past_length = torch.zeros(1, batch_size, dtype=torch.int32, device=device) + + return [empty_memory, left_context_key, left_context_val, past_length] + + @torch.jit.export + def batch_state(self, states: List[List[Tensor]]) -> List[Tensor]: + if len(states) == 0: + return [] + batched_m = [] + batched_lc_key = [] + batched_lc_val = [] + batched_past_length = [] + for state in states: + if len(state) == 0: + continue + m, lc_key, lc_val, past_length = state + batched_m.append(m) + batched_lc_key.append(lc_key) + batched_lc_val.append(lc_val) + batched_past_length.append(past_length) + + if ( + (len(batched_m) == 0) + or (len(batched_lc_key) == 0) + or (len(batched_lc_val) == 0) + or (len(batched_past_length) == 0) + ): + return [ + torch.tensor([]), + torch.tensor([]), + torch.tensor([]), + torch.tensor([]), + ] + + batched_m = torch.cat(batched_m, dim=2) + batched_lc_key = torch.cat(batched_lc_key, dim=2) + batched_lc_val = torch.cat(batched_lc_val, dim=2) + batched_past_length = torch.cat(batched_past_length, dim=1) + return [batched_m, batched_lc_key, batched_lc_val, batched_past_length] + + @torch.jit.export + def reorder_state(self, state: List[Tensor], indices: Tensor) -> List[Tensor]: + if len(state) == 0: + return [] + m, lc_key, lc_val, past_length = state + indices = indices.to(device=m.device) + reord_m = torch.index_select(m, 2, indices) + reord_lc_key = torch.index_select(lc_key, 2, indices) + reord_lc_val = torch.index_select(lc_val, 2, indices) + reord_past_length = torch.index_select(past_length, 1, indices) + return [reord_m, reord_lc_key, reord_lc_val, reord_past_length] + + @torch.jit.export + def reset_state(self, state: List[Tensor], indices: Tensor) -> List[Tensor]: + m, lc_key, lc_val, past_length = state + m = m.index_fill(dim=2, index=indices, value=0.0) + lc_key = lc_key.index_fill(dim=2, index=indices, value=0.0) + lc_val = lc_val.index_fill(dim=2, index=indices, value=0.0) + past_length = past_length.index_fill(dim=1, index=indices, value=0) + + return [m, lc_key, lc_val, past_length] + + @torch.jit.export + def state_size(self) -> int: + return 4 + + @torch.jit.export + def batch_size_in_state( + self, state: Optional[List[Tensor]], sloppy: bool = True + ) -> Optional[int]: + if state is None: + return None + return state[0].size(2) + + def gen_summary_queries(self, input): + sum_input = self.memory_op(input) + return sum_input + + def _gen_right_context_padded_input(self, input): + # This function deals with input that is already + # padded with right context (e.g. minibatch training) + right_context_blocks = [] + T, B, D = input.shape + num_segs = math.ceil((T - self.right_context) / self.segment_size) + for i in range(0, num_segs - 1): + st = (i + 1) * self.segment_size + ed = st + self.right_context + assert ed < T + temp = input[st:ed, :, :] + right_context_blocks.append(temp) + + # last segment right context is already available + right_context_blocks.append(input[T - self.right_context :, :, :]) + return torch.cat(right_context_blocks, dim=0) + + def _gen_segs_right_context(self, input, lengths): + segments = [] + T, B, D = input.size() + nT = T - self.right_context + + # assume input is right context padded + num_segs = math.ceil(nT / self.segment_size) + # pad zeros to the utterance to make sure each + # segment has the same right context. For the + for i in range(0, num_segs - 1): + st = i * self.segment_size + ed = min(T, st + self.segment_size + self.right_context) + temp = input[st:ed, :, :] + rest_lengths = torch.clamp( + lengths - self.segment_size, min=0, max=nT - (i + 1) * self.segment_size + ) + segments.append((temp, lengths - rest_lengths + self.right_context)) + lengths = rest_lengths + + last_seg = input[st + self.segment_size :, :, :] + segments.append((last_seg, rest_lengths + self.right_context)) + + return segments + + @torch.jit.unused + def forward( + self, input: Tensor, padding_masks: Tensor, state: Optional[List[Tensor]] = None + ) -> Tuple[Tensor, Tensor, List[Tensor], List[Tensor]]: + # Xutai: originally the second argument is lengths. + lengths = (~padding_masks).sum(dim=1).long() + # mini batch training. + if self.mini_batches: + return self.forward_mini_batches(input, lengths, state) + + # regular full sequence training. Note, assume the right context in provided + # in the input. + T, B, D = input.size() + right_context_blocks = self._gen_right_context_padded_input(input) + + # generate the relative positional embedding + if self.use_rpe: + rpe = self._get_relative_position( + input=input, + max_relative_position=self.max_relative_position, + left_context_length=0, + past_length=0, + is_decoding=False, + ) + else: + rpe = None + input = input[: T - self.right_context, :, :] + + attention_mask = self._get_attention_mask(input) + + # firt layer use each segment mean as memory + # ignore the last one seg average + if self.use_mem: + mems = self.gen_summary_queries(input)[:-1, :, :] + else: + mems = torch.zeros(0, input.size(1), input.size(2), device=input.device) + mems = mems.type_as(input) + + output = input + all_outputs = [] + + for layer in self.layers: + output, mems, right_context_blocks, _, _ = layer( + input=output, + lengths=lengths, + attention_mask=attention_mask, + mems=mems, + right_context_blocks=right_context_blocks, + pre_mems=None, + left_context_key=None, + left_context_val=None, + rpe=rpe, + ) + all_outputs.append(output) + return output, padding_masks, [], all_outputs + + def forward_jit_mini_batch_init( + self, + seg: Tensor, + state: Optional[List[Tensor]] = None, + is_decoding: bool = False, + ): + # Prepare state. In whole sequence training, state is ignored. + # For minibatch training, we need to prepare state + if state is None: + state = self.init_state(batch_size=seg.size(1), device=seg.device) + if seg.dtype == torch.half: + state = [state[0].half(), state[1].half(), state[2].half(), state[3]] + + if self.use_mem: + # note input average only on seg, not on right context + # first layer use each segmetn mean as memory. the last + # one segment average is used in state + full_mems = self.gen_summary_queries(seg) + if is_decoding: + mems = full_mems[0:1, :, :] + state_mems = torch.cat([state[0][0], mems], dim=0) + else: + mems = full_mems[:-1, :, :] + state_mems = torch.cat([state[0][0], full_mems], dim=0) + else: + mems = state[0][0] + state_mems = mems + + # track processed segment number or memory number + # the same batch as the same bumber of past length + past_length = state[3][0][0].item() + past_left_context = min(past_length * self.segment_size, self.left_context) + past_length = min(self.max_memory_size, past_length) + + return state, mems, state_mems, past_length, past_left_context + + def state_update_before( + self, layer: int, state: List[Tensor], past_length: int, past_left_context: int + ): + pre_mems = state[0][layer][self.max_memory_size - past_length :, :, :] + lc_key = state[1][layer][self.left_context - past_left_context :, :, :] + lc_val = state[2][layer][self.left_context - past_left_context :, :, :] + return pre_mems, lc_key, lc_val + + def state_update_after( + self, + layer: int, + state: List[Tensor], + mems: Tensor, + next_key: Tensor, + next_val: Tensor, + mems_list: List[Tensor], + lc_key_list: List[Tensor], + lc_val_list: List[Tensor], + ): + # mems is used for next layer + if layer < self.num_layers - 1: + state_mems = torch.cat([state[0][layer + 1], mems], dim=0) + mems_list.append(state_mems[-self.max_memory_size :, :, :]) + + # when mems pass to next sequence, we need the last memory. when mems + # use for the next layer, we can ignore the last memory + mems = mems[:-1, :, :] + + # note state[1][i] and state[2][i] original length equals to self.left_context + new_k = torch.cat([state[1][layer], next_key], dim=0) + new_v = torch.cat([state[2][layer], next_val], dim=0) + lc_key_list.append(new_k[-self.left_context :, :, :]) + lc_val_list.append(new_v[-self.left_context :, :, :]) + return mems_list, lc_key_list, lc_val_list, mems + + def state_update_after_loop( + self, + state: List[Tensor], + mems_list: List[Tensor], + lc_key_list: List[Tensor], + lc_val_list: List[Tensor], + update_length: int, + ): + state[0] = torch.stack(mems_list, dim=0) + state[1] = torch.stack(lc_key_list, dim=0) + state[2] = torch.stack(lc_val_list, dim=0) + state[3] = state[3] + update_length + return state + + @torch.jit.unused + def forward_mini_batches( + self, input: Tensor, lengths: Tensor, state: Optional[List[Tensor]] = None + ) -> Tuple[Tensor, Tensor, List[Tensor], List[Tensor]]: + T, B, D = input.size() + + # input without right context + seg = input[: T - self.right_context, :, :] + + # get right context blocks + right_context_blocks = self._gen_right_context_padded_input(input) + + mems_list = [] + lc_key_list = [] + lc_val_list = [] + results = self.forward_jit_mini_batch_init(seg, state, False) + state, mems, state_mems, past_length, past_left_context = results + + # relative position embedding + if self.use_rpe: + rpe = self._get_relative_position( + input=input, + max_relative_position=self.max_relative_position, + left_context_length=past_left_context, + past_length=past_length, + is_decoding=False, + ) + else: + rpe = None + + # get attention mask based on seg (not include right context) and available + # left context + attention_mask = self._get_attention_mask(seg, past_length, past_left_context) + mems_list.append(state_mems[-self.max_memory_size :, :, :]) + output = seg + i = 0 + all_outputs = [] + for layer in self.layers: + # In order to make cross stream batching work, mem, left context key + # and left context value in the state should always be the same shape. + # We use the past length to track the processed segment number. In this + # way, we take out the essential memory, left context key and left + # context val from the state. After finish the forward for current segment + # we add the new memory, left context key and left context value into the + # staate and trim out the oldest part to keep the shape consistent. + pre_mems, lc_key, lc_val = self.state_update_before( + i, state, past_length, past_left_context + ) + + output, mems, right_context_blocks, next_key, next_val = layer.forward( + input=output, + lengths=lengths, + attention_mask=attention_mask, + mems=mems, + right_context_blocks=right_context_blocks, + pre_mems=pre_mems, + left_context_key=lc_key, + left_context_val=lc_val, + rpe=rpe, + ) + all_outputs.append(output) + mems_list, lc_key_list, lc_val_list, mems = self.state_update_after( + layer=i, + state=state, + mems=mems, + next_key=next_key, + next_val=next_val, + mems_list=mems_list, + lc_key_list=lc_key_list, + lc_val_list=lc_val_list, + ) + + i += 1 + + # update state + update_length = math.ceil((T - self.right_context) / self.segment_size) + state = self.state_update_after_loop( + state=state, + mems_list=mems_list, + lc_key_list=lc_key_list, + lc_val_list=lc_val_list, + update_length=update_length, + ) + + return output, lengths, state, all_outputs + + def forward_jit_test( + self, input: Tensor, lengths: Tensor, state: Optional[List[Tensor]] = None + ) -> Tuple[Tensor, Tensor, List[Tensor]]: + """ + This one simulate sequence encoder forward jit. This is for unit test purpose. + It is not used in training or decoding. Note, extra_right_context is set in + the model. In unit test, input = [utterance, right_context], lengths = + [utterance_length]. + args: + input: input utterance + lengths: utterance input length + state: None here. input is whole utterance + """ + # [TODO] sequence_to_segment has bug in lengths. + seg_src_tokens_lengths = self._gen_segs_right_context(input, lengths) + + seg_enc_tokens_lengths: List[Tuple[Tensor, Tensor]] = [] + state: Optional[List[Tensor]] = None + for seg_src_tokens, seg_src_lengths in seg_src_tokens_lengths: + seg_enc_tokens, seg_enc_lengths, state = self.forward_jit( + input=seg_src_tokens, lengths=seg_src_lengths, state=state + ) + seg_enc_tokens_lengths.append((seg_enc_tokens, seg_enc_lengths)) + + enc_tokens, enc_lengths = segments_to_sequence( + segments=seg_enc_tokens_lengths, time_axis=0 + ) + + state = [] # returns trivial state + + return enc_tokens, enc_lengths, state + + @torch.jit.export + def forward_jit( + self, input: Tensor, lengths: Tensor, state: Optional[List[Tensor]] = None + ) -> Tuple[Tensor, Tensor, List[Tensor]]: + """ + Forward helper for online decoding. + + args: + input: [seg, right_context]. We assume in online we + always padding the right context to the preset right context size. + For the last segment, we may have short segment size, but right + context size is the same as other segments + lengths: utterance input length is the utterance segment length and + right context size + state: [memory, left_context_key, left_context_val]. To improve throughput, + in addition to memory, we also cache key and value for left_context in + multihead self-attention + """ + # In online decoding, input = [segment, right_context] + # Lengths = [segment_length, right_context_length] + # so we need strip right context in output + T, B, D = input.size() + rc_str = T - self.right_context + rc_end = T + right_context_blocks = input[rc_str:rc_end, :, :] + seg = input[:rc_str, :, :] + lengths = torch.clamp(lengths - self.right_context, min=0) + mems_list = [] + lc_key_list = [] + lc_val_list = [] + + results = self.forward_jit_mini_batch_init(seg, state, True) + state, mems, state_mems, past_length, past_left_context = results + + # relative position embedding + if self.use_rpe: + rpe = self._get_relative_position( + input=input, + max_relative_position=self.max_relative_position, + left_context_length=past_left_context, + past_length=past_length, + is_decoding=True, + ) + else: + rpe = None + + # memory for first layer. + mems_list.append(state_mems[-self.max_memory_size :, :, :]) + output = seg + i = 0 + for layer in self.layers: + # In order to make cross stream batching work, mem, left context key + # and left context value in the state should always be the same shape. + # We use the past length to track the processed segment number. In this + # way, we take out the essential memory, left context key and left + # context val from the state. After finish the forward for current segment + # we add the new memory, left context key and left context value into the + # staate and trim out the oldest part to keep the shape consistent. + true_mems, lc_key, lc_val = self.state_update_before( + layer=i, + state=state, + past_length=past_length, + past_left_context=past_left_context, + ) + + output, mems, right_context_blocks, next_key, next_val = layer.forward_jit( + input=output, + lengths=lengths, + mems=true_mems, + right_context_blocks=right_context_blocks, + left_context_key=lc_key, + left_context_val=lc_val, + rpe=rpe, + ) + # mems is used for next layer + mems_list, lc_key_list, lc_val_list, _ = self.state_update_after( + layer=i, + state=state, + mems_list=mems_list, + mems=mems, + next_key=next_key, + next_val=next_val, + lc_key_list=lc_key_list, + lc_val_list=lc_val_list, + ) + i += 1 + + # update state + state = self.state_update_after_loop( + state=state, + mems_list=mems_list, + lc_key_list=lc_key_list, + lc_val_list=lc_val_list, + update_length=1, + ) + + return output, lengths, state + + def quantize_(self, params=None): + if params and "per_channel" in params and params["per_channel"]: + qconfig = per_channel_dynamic_qconfig + else: + qconfig = default_dynamic_qconfig + quantization.quantize_dynamic( + self, {torch.nn.Linear: qconfig}, dtype=torch.qint8, inplace=True + ) + return self + + +# ------------------------------------------------------------------------------ +# Emformer encoder for seq2seq model +# This is a wrapper over the original emformer +# ------------------------------------------------------------------------------ +def emformer_encoder(klass): + class SpeechEncoder(klass): + def __init__(self, args): + super().__init__(args) + stride = SpeechEncoder.conv_layer_stride(args) + trf_left_context = args.segment_left_context // stride + trf_right_context = args.segment_right_context // stride + context_config = [trf_left_context, trf_right_context] + self.transformer_layers = nn.ModuleList( + [ + NoSegAugmentedMemoryTransformerEncoderLayer( + input_dim=args.encoder_embed_dim, + num_heads=args.encoder_attention_heads, + ffn_dim=args.encoder_ffn_embed_dim, + num_layers=args.encoder_layers, + dropout_in_attn=args.dropout, + dropout_on_attn=args.dropout, + dropout_on_fc1=args.dropout, + dropout_on_fc2=args.dropout, + activation_fn=args.activation_fn, + context_config=context_config, + segment_size=args.segment_length, + max_memory_size=args.max_memory_size, + scaled_init=True, # TODO: use constant for now. + tanh_on_mem=args.amtrf_tanh_on_mem, + ) + ] + ) + + def forward(self, src_tokens, src_lengths): + encoder_out = super().forward(src_tokens, src_lengths) + output = encoder_out["encoder_out"][0] + encoder_padding_masks = encoder_out["encoder_padding_mask"][0] + + # This is because that in the original implementation + # the output didn't consider the last segment as right context. + encoder_padding_masks = encoder_padding_masks[:, : output.size(0)] + + return { + "encoder_out": [output], + "encoder_padding_mask": [encoder_padding_masks], + "encoder_embedding": [], + "encoder_states": [], + "src_tokens": [], + "src_lengths": [], + } + + @staticmethod + def conv_layer_stride(args): + # TODO: make it configurable from the args + return 4 + + SpeechEncoder.__name__ = klass.__name__ + return SpeechEncoder diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/multi_modality_model.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/multi_modality_model.py new file mode 100644 index 00000000..04642162 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/multi_modality_model.py @@ -0,0 +1,49 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.models import FairseqDecoder, FairseqEncoder + + +# a container for different encoders with training samples from different modality +# each time, only one encoder is selected +class MultiModalityEncoder(FairseqEncoder): + def __init__(self, dictionary): + super().__init__(dictionary) + + def select_encoder(self, mode, **kwargs): + raise NotImplementedError("Model must implement the select_encoder method") + return None, kwargs + + # def post_encoder(self, encoder_out, src_tokens, src_lengths, mode, **kwargs): + # # Default do nothing + # return encoder_out + + # get sample data from JointSpeechTextDataset + def forward(self, src_tokens, src_lengths=None, mode="", **kwargs): + encoder, kwargs = self.select_encoder(mode, **kwargs) + # return self.post_encoder(encoder(src_tokens, src_lengths, **kwargs), src_tokens, src_lengths, mode, **kwargs) + return encoder(src_tokens, src_lengths, **kwargs) + + +# a container for different decoders with training samples from different modality +# each time, only one decoder is selected +class MultiInputDecoder(FairseqDecoder): + def __init__(self, dictionary): + super().__init__(dictionary) + + def select_decoder(self, mode, **kwargs): + raise NotImplementedError("Model must implement the select_decoder method") + return None, kwargs + + def forward( + self, prev_output_tokens, encoder_out, incremental_state=None, mode="", **kwargs + ): + decoder, kwargs = self.select_decoder(mode, **kwargs) + return decoder( + prev_output_tokens, + encoder_out, + incremental_state=incremental_state, + **kwargs + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_conformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_conformer.py new file mode 100644 index 00000000..fbac61d5 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_conformer.py @@ -0,0 +1,159 @@ +import logging +import torch +from fairseq.models.speech_to_text.s2t_transformer import ( + S2TTransformerEncoder, + S2TTransformerModel, + Conv1dSubsampler, + base_architecture as transformer_base_architecture, +) +from fairseq.data.data_utils import lengths_to_padding_mask +from fairseq.modules.conformer_layer import ConformerEncoderLayer +from fairseq.models import FairseqEncoder, register_model_architecture, register_model +from fairseq.modules import PositionalEmbedding, RelPositionalEncoding +import math + +logger = logging.getLogger(__name__) + + +class S2TConformerEncoder(FairseqEncoder): + """Conformer Encoder for speech translation based on https://arxiv.org/abs/2005.08100""" + + def __init__(self, args): + super().__init__(None) + self.embed_scale = math.sqrt(args.encoder_embed_dim) + if args.no_scale_embedding: + self.embed_scale = 1.0 + self.padding_idx = 1 + self.subsample = Conv1dSubsampler( + args.input_feat_per_channel * args.input_channels, + args.conv_channels, + args.encoder_embed_dim, + [int(k) for k in args.conv_kernel_sizes.split(",")], + ) + self.pos_enc_type = args.pos_enc_type + if self.pos_enc_type == "rel_pos": + self.embed_positions = RelPositionalEncoding( + args.max_source_positions, args.encoder_embed_dim + ) + elif self.pos_enc_type == "rope": + self.embed_positions = None + else: # Use absolute positional embedding + self.pos_enc_type = "abs" + self.embed_positions = PositionalEmbedding( + args.max_source_positions, args.encoder_embed_dim, self.padding_idx + ) + + self.linear = torch.nn.Linear(args.encoder_embed_dim, args.encoder_embed_dim) + self.dropout = torch.nn.Dropout(args.dropout) + self.conformer_layers = torch.nn.ModuleList( + [ + ConformerEncoderLayer( + embed_dim=args.encoder_embed_dim, + ffn_embed_dim=args.encoder_ffn_embed_dim, + attention_heads=args.encoder_attention_heads, + dropout=args.dropout, + depthwise_conv_kernel_size=args.depthwise_conv_kernel_size, + attn_type=args.attn_type, + pos_enc_type=self.pos_enc_type, + use_fp16=args.fp16, + ) + for _ in range(args.encoder_layers) + ] + ) + + def forward(self, src_tokens, src_lengths, return_all_hiddens=False): + """ + Args: + src_tokens: Input source tokens Tensor of shape B X T X C + src_lengths: Lengths Tensor corresponding to input source tokens + return_all_hiddens: If true will append the self attention states to the encoder states + Returns: + encoder_out: Tensor of shape B X T X C + encoder_padding_mask: Optional Tensor with mask + encoder_embedding: Optional Tensor. Always empty here + encoder_states: List of Optional Tensors wih self attention states + src_tokens: Optional Tensor. Always empty here + src_lengths: Optional Tensor. Always empty here + """ + x, input_lengths = self.subsample(src_tokens, src_lengths) # returns T X B X C + encoder_padding_mask = lengths_to_padding_mask(input_lengths) + x = self.embed_scale * x + if self.pos_enc_type == "rel_pos": + positions = self.embed_positions(x) + + elif self.pos_enc_type == "rope": + positions = None + + else: + positions = self.embed_positions(encoder_padding_mask).transpose(0, 1) + x += positions + positions = None + + x = self.linear(x) + x = self.dropout(x) + encoder_states = [] + + # x is T X B X C + for layer in self.conformer_layers: + x, _ = layer(x, encoder_padding_mask, positions) + if return_all_hiddens: + encoder_states.append(x) + + return { + "encoder_out": [x], # T x B x C + "encoder_padding_mask": [encoder_padding_mask] + if encoder_padding_mask.any() + else [], # B x T + "encoder_embedding": [], # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], + "src_lengths": [], + } + + def reorder_encoder_out(self, encoder_out, new_order): + """Required method for a FairseqEncoder. Calls the method from the parent class""" + return S2TTransformerEncoder.reorder_encoder_out(self, encoder_out, new_order) + + +@register_model("s2t_conformer") +class S2TConformerModel(S2TTransformerModel): + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + + @staticmethod + def add_args(parser): + S2TTransformerModel.add_args(parser) + parser.add_argument("--input-feat-per-channel", default=80) + parser.add_argument("--depthwise-conv-kernel-size", default=31) + parser.add_argument("--input-channels", default=1) + parser.add_argument( + "--attn-type", + default=None, + help="If not specified uses fairseq MHA. Other valid option is espnet", + ) + parser.add_argument( + "--pos-enc-type", + default="abs", + help="Must be specified in addition to attn-type=espnet for rel_pos and rope", + ) + + @classmethod + def build_encoder(cls, args): + encoder = S2TConformerEncoder(args) + return encoder + + +@register_model_architecture("s2t_conformer", "s2t_conformer") +def base_architecture(args): + args.attn_type = getattr(args, "attn_type", None) + args.pos_enc_type = getattr(args, "pos_enc_type", "abs") + args.input_feat_per_channel = getattr(args, "input_feat_per_channel", 80) + args.input_channels = getattr(args, "input_channels", 1) + args.max_source_positions = getattr(args, "max_source_positions", 6000) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.dropout = getattr(args, "dropout", 0.1) + args.encoder_layers = getattr(args, "encoder_layers", 16) + args.depthwise_conv_kernel_size = getattr(args, "depthwise_conv_kernel_size", 31) + transformer_base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_transformer.py new file mode 100644 index 00000000..4b43e1ac --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_transformer.py @@ -0,0 +1,569 @@ +#!/usr/bin/env python3 + +import logging +import math +from pathlib import Path +from typing import Dict, List, Optional, Tuple + +import torch +import torch.nn as nn +from torch import Tensor + +from fairseq import checkpoint_utils, utils +from fairseq.data.data_utils import lengths_to_padding_mask +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + register_model, + register_model_architecture, +) +from fairseq.models.speech_to_text.hub_interface import S2THubInterface +from fairseq.models.transformer import Embedding, TransformerDecoder +from fairseq.modules import ( + FairseqDropout, + LayerNorm, + PositionalEmbedding, + TransformerEncoderLayer, +) + +logger = logging.getLogger(__name__) + + +class Conv1dSubsampler(nn.Module): + """Convolutional subsampler: a stack of 1D convolution (along temporal + dimension) followed by non-linear activation via gated linear units + (https://arxiv.org/abs/1911.08460) + + Args: + in_channels (int): the number of input channels + mid_channels (int): the number of intermediate channels + out_channels (int): the number of output channels + kernel_sizes (List[int]): the kernel size for each convolutional layer + """ + + def __init__( + self, + in_channels: int, + mid_channels: int, + out_channels: int, + kernel_sizes: List[int] = (3, 3), + ): + super(Conv1dSubsampler, self).__init__() + self.n_layers = len(kernel_sizes) + self.conv_layers = nn.ModuleList( + nn.Conv1d( + in_channels if i == 0 else mid_channels // 2, + mid_channels if i < self.n_layers - 1 else out_channels * 2, + k, + stride=2, + padding=k // 2, + ) + for i, k in enumerate(kernel_sizes) + ) + + def get_out_seq_lens_tensor(self, in_seq_lens_tensor): + out = in_seq_lens_tensor.clone() + for _ in range(self.n_layers): + out = ((out.float() - 1) / 2 + 1).floor().long() + return out + + def forward(self, src_tokens, src_lengths): + bsz, in_seq_len, _ = src_tokens.size() # B x T x (C x D) + x = src_tokens.transpose(1, 2).contiguous() # -> B x (C x D) x T + for conv in self.conv_layers: + x = conv(x) + x = nn.functional.glu(x, dim=1) + _, _, out_seq_len = x.size() + x = x.transpose(1, 2).transpose(0, 1).contiguous() # -> T x B x (C x D) + return x, self.get_out_seq_lens_tensor(src_lengths) + + +@register_model("s2t_transformer") +class S2TTransformerModel(FairseqEncoderDecoderModel): + """Adapted Transformer model (https://arxiv.org/abs/1706.03762) for + speech-to-text tasks. The Transformer encoder/decoder remains the same. + A trainable input subsampler is prepended to the Transformer encoder to + project inputs into the encoder dimension as well as downsample input + sequence for computational efficiency.""" + + @classmethod + def hub_models(cls): + base_url = "http://dl.fbaipublicfiles.com/fairseq/s2t" + model_ids = [ + "s2t_transformer_s-en-asr-librispeech", + "s2t_transformer_m-en-asr-librispeech", + "s2t_transformer_l-en-asr-librispeech", + ] + return {i: f"{base_url}/{i}.tar.gz" for i in model_ids} + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + config_yaml="config.yaml", + **kwargs, + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + config_yaml=config_yaml, + **kwargs, + ) + return S2THubInterface(x["args"], x["task"], x["models"][0]) + + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + # input + parser.add_argument( + "--conv-kernel-sizes", + type=str, + metavar="N", + help="kernel sizes of Conv1d subsampling layers", + ) + parser.add_argument( + "--conv-channels", + type=int, + metavar="N", + help="# of channels in Conv1d subsampling layers", + ) + # Transformer + parser.add_argument( + "--activation-fn", + type=str, + default="relu", + choices=utils.get_available_activation_fns(), + help="activation function to use", + ) + parser.add_argument( + "--dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--attention-dropout", + type=float, + metavar="D", + help="dropout probability for attention weights", + ) + parser.add_argument( + "--activation-dropout", + "--relu-dropout", + type=float, + metavar="D", + help="dropout probability after activation in FFN.", + ) + parser.add_argument( + "--encoder-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension", + ) + parser.add_argument( + "--encoder-ffn-embed-dim", + type=int, + metavar="N", + help="encoder embedding dimension for FFN", + ) + parser.add_argument( + "--encoder-layers", type=int, metavar="N", help="num encoder layers" + ) + parser.add_argument( + "--encoder-attention-heads", + type=int, + metavar="N", + help="num encoder attention heads", + ) + parser.add_argument( + "--encoder-normalize-before", + action="store_true", + help="apply layernorm before each encoder block", + ) + parser.add_argument( + "--decoder-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension", + ) + parser.add_argument( + "--decoder-ffn-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension for FFN", + ) + parser.add_argument( + "--decoder-layers", type=int, metavar="N", help="num decoder layers" + ) + parser.add_argument( + "--decoder-attention-heads", + type=int, + metavar="N", + help="num decoder attention heads", + ) + parser.add_argument( + "--decoder-normalize-before", + action="store_true", + help="apply layernorm before each decoder block", + ) + parser.add_argument( + "--share-decoder-input-output-embed", + action="store_true", + help="share decoder input and output embeddings", + ) + parser.add_argument( + "--layernorm-embedding", + action="store_true", + help="add layernorm to embedding", + ) + parser.add_argument( + "--no-scale-embedding", + action="store_true", + help="if True, dont scale embeddings", + ) + parser.add_argument( + "--load-pretrained-encoder-from", + type=str, + metavar="STR", + help="model to take encoder weights from (for initialization)", + ) + parser.add_argument( + "--encoder-freezing-updates", + type=int, + metavar="N", + help="freeze encoder for first N updates", + ) + + @classmethod + def build_encoder(cls, args): + encoder = S2TTransformerEncoder(args) + pretraining_path = getattr(args, "load_pretrained_encoder_from", None) + if pretraining_path is not None: + if not Path(pretraining_path).exists(): + logger.warning( + f"skipped pretraining because {pretraining_path} does not exist" + ) + else: + encoder = checkpoint_utils.load_pretrained_component_from_model( + component=encoder, checkpoint=pretraining_path + ) + logger.info(f"loaded pretrained encoder from: {pretraining_path}") + return encoder + + @classmethod + def build_decoder(cls, args, task, embed_tokens): + return TransformerDecoderScriptable(args, task.target_dictionary, embed_tokens) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present in older models + base_architecture(args) + + def build_embedding(dictionary, embed_dim): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + return Embedding(num_embeddings, embed_dim, padding_idx) + + decoder_embed_tokens = build_embedding( + task.target_dictionary, args.decoder_embed_dim + ) + args.tgt_dict_size = len(task.target_dictionary) + encoder = cls.build_encoder(args) + decoder = cls.build_decoder(args, task, decoder_embed_tokens) + return cls(encoder, decoder) + + def get_normalized_probs( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + log_probs: bool, + sample: Optional[Dict[str, Tensor]] = None, + ): + # net_output['encoder_out'] is a (B, T, D) tensor + lprobs = self.get_normalized_probs_scriptable(net_output, log_probs, sample) + lprobs.batch_first = True + return lprobs + + def get_ctc_target(self, sample: Optional[Dict[str, Tensor]]): + return sample["target"], sample["target_lengths"] + + def get_ctc_output( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + sample: Optional[Dict[str, Tensor]], + ): + encoder_out = net_output[1]["encoder_out"]["encoder_out"][0] + logits = self.encoder.ctc_proj(encoder_out) # T x B x C + out = utils.log_softmax(logits.float(), dim=-1) + padding_mask = net_output[1]["encoder_out"]["encoder_padding_mask"] + lens = out.new_full((out.shape[1],), out.shape[0]).long() + if len(padding_mask) > 0: + lens -= padding_mask[0].sum(dim=-1) + return out, lens + + def forward(self, src_tokens, src_lengths, prev_output_tokens): + """ + The forward method inherited from the base class has a **kwargs + argument in its input, which is not supported in torchscript. This + method overwrites the forward method definition without **kwargs. + """ + encoder_out = self.encoder(src_tokens=src_tokens, src_lengths=src_lengths) + decoder_out = self.decoder( + prev_output_tokens=prev_output_tokens, encoder_out=encoder_out + ) + return decoder_out + + +class S2TTransformerEncoder(FairseqEncoder): + """Speech-to-text Transformer encoder that consists of input subsampler and + Transformer encoder.""" + + def __init__(self, args): + super().__init__(None) + + self.encoder_freezing_updates = args.encoder_freezing_updates + self.num_updates = 0 + + self.dropout_module = FairseqDropout( + p=args.dropout, module_name=self.__class__.__name__ + ) + self.embed_scale = math.sqrt(args.encoder_embed_dim) + if args.no_scale_embedding: + self.embed_scale = 1.0 + self.padding_idx = 1 + + self.subsample = Conv1dSubsampler( + args.input_feat_per_channel * args.input_channels, + args.conv_channels, + args.encoder_embed_dim, + [int(k) for k in args.conv_kernel_sizes.split(",")], + ) + + self.embed_positions = PositionalEmbedding( + args.max_source_positions, args.encoder_embed_dim, self.padding_idx + ) + + self.transformer_layers = nn.ModuleList( + [TransformerEncoderLayer(args) for _ in range(args.encoder_layers)] + ) + if args.encoder_normalize_before: + self.layer_norm = LayerNorm(args.encoder_embed_dim) + else: + self.layer_norm = None + + self.ctc_proj = None + if getattr(args, "ctc_weight", 0.0) > 0.0: + self.ctc_proj = nn.Linear(args.encoder_embed_dim, args.tgt_dict_size) + + def _forward(self, src_tokens, src_lengths, return_all_hiddens=False): + x, input_lengths = self.subsample(src_tokens, src_lengths) + x = self.embed_scale * x + + encoder_padding_mask = lengths_to_padding_mask(input_lengths) + positions = self.embed_positions(encoder_padding_mask).transpose(0, 1) + x += positions + x = self.dropout_module(x) + + encoder_states = [] + + for layer in self.transformer_layers: + x = layer(x, encoder_padding_mask) + if return_all_hiddens: + encoder_states.append(x) + + if self.layer_norm is not None: + x = self.layer_norm(x) + + return { + "encoder_out": [x], # T x B x C + "encoder_padding_mask": [encoder_padding_mask] + if encoder_padding_mask.any() + else [], # B x T + "encoder_embedding": [], # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], + "src_lengths": [], + } + + def forward(self, src_tokens, src_lengths, return_all_hiddens=False): + if self.num_updates < self.encoder_freezing_updates: + with torch.no_grad(): + x = self._forward( + src_tokens, src_lengths, return_all_hiddens=return_all_hiddens + ) + else: + x = self._forward( + src_tokens, src_lengths, return_all_hiddens=return_all_hiddens + ) + return x + + def reorder_encoder_out(self, encoder_out, new_order): + new_encoder_out = ( + [] + if len(encoder_out["encoder_out"]) == 0 + else [x.index_select(1, new_order) for x in encoder_out["encoder_out"]] + ) + + new_encoder_padding_mask = ( + [] + if len(encoder_out["encoder_padding_mask"]) == 0 + else [ + x.index_select(0, new_order) + for x in encoder_out["encoder_padding_mask"] + ] + ) + + new_encoder_embedding = ( + [] + if len(encoder_out["encoder_embedding"]) == 0 + else [ + x.index_select(0, new_order) for x in encoder_out["encoder_embedding"] + ] + ) + + encoder_states = encoder_out["encoder_states"] + if len(encoder_states) > 0: + for idx, state in enumerate(encoder_states): + encoder_states[idx] = state.index_select(1, new_order) + + return { + "encoder_out": new_encoder_out, # T x B x C + "encoder_padding_mask": new_encoder_padding_mask, # B x T + "encoder_embedding": new_encoder_embedding, # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], # B x T + "src_lengths": [], # B x 1 + } + + def set_num_updates(self, num_updates): + super().set_num_updates(num_updates) + self.num_updates = num_updates + + +class TransformerDecoderScriptable(TransformerDecoder): + def extract_features( + self, + prev_output_tokens, + encoder_out: Optional[Dict[str, List[Tensor]]] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + full_context_alignment: bool = False, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + ): + # call scriptable method from parent class + x, _ = self.extract_features_scriptable( + prev_output_tokens, + encoder_out, + incremental_state, + full_context_alignment, + alignment_layer, + alignment_heads, + ) + extra = {"encoder_out": encoder_out} if incremental_state is None else None + return x, extra + + +@register_model_architecture(model_name="s2t_transformer", arch_name="s2t_transformer") +def base_architecture(args): + args.encoder_freezing_updates = getattr(args, "encoder_freezing_updates", 0) + # Convolutional subsampler + args.conv_kernel_sizes = getattr(args, "conv_kernel_sizes", "5,5") + args.conv_channels = getattr(args, "conv_channels", 1024) + # Transformer + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 12) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", True) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", True) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", args.dropout) + args.activation_dropout = getattr(args, "activation_dropout", args.dropout) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.decoder_layerdrop = getattr(args, "decoder_layerdrop", 0.0) + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + args.quant_noise_pq = getattr(args, "quant_noise_pq", 0) + + +@register_model_architecture("s2t_transformer", "s2t_transformer_s") +def s2t_transformer_s(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 256 * 8) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 4) + args.dropout = getattr(args, "dropout", 0.1) + base_architecture(args) + + +@register_model_architecture("s2t_transformer", "s2t_transformer_xs") +def s2t_transformer_xs(args): + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.decoder_layers = getattr(args, "decoder_layers", 3) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 256 * 4) + args.dropout = getattr(args, "dropout", 0.3) + s2t_transformer_s(args) + + +@register_model_architecture("s2t_transformer", "s2t_transformer_sp") +def s2t_transformer_sp(args): + args.encoder_layers = getattr(args, "encoder_layers", 16) + s2t_transformer_s(args) + + +@register_model_architecture("s2t_transformer", "s2t_transformer_m") +def s2t_transformer_m(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 512 * 4) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.dropout = getattr(args, "dropout", 0.15) + base_architecture(args) + + +@register_model_architecture("s2t_transformer", "s2t_transformer_mp") +def s2t_transformer_mp(args): + args.encoder_layers = getattr(args, "encoder_layers", 16) + s2t_transformer_m(args) + + +@register_model_architecture("s2t_transformer", "s2t_transformer_l") +def s2t_transformer_l(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 1024 * 4) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 16) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 16) + args.dropout = getattr(args, "dropout", 0.2) + base_architecture(args) + + +@register_model_architecture("s2t_transformer", "s2t_transformer_lp") +def s2t_transformer_lp(args): + args.encoder_layers = getattr(args, "encoder_layers", 16) + s2t_transformer_l(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_wav_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_wav_transformer.py new file mode 100644 index 00000000..f1103481 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/s2t_wav_transformer.py @@ -0,0 +1,485 @@ +#!/usr/bin/env python3 + +import math + +import torch +import torch.nn as nn + +from fairseq.data.data_utils import compute_mask_indices +from fairseq.models import FairseqEncoder +from fairseq.models.wav2vec import ConvFeatureExtractionModel +from fairseq.modules import GradMultiply, LayerNorm, SamePad, TransformerEncoderLayer + + +# Transformer encoder with wave input, it is adopted from wav2vec 2.0 Encoder. +# use wav input +# use trained position embedding so it is easier to match with text input +class SpeechWavTransformerEncoder(FairseqEncoder): + + # extra parameters for speech encoder besides those defined in transformermodel + @staticmethod + def add_args(parser): + parser.add_argument( + "--dropout-input", + type=float, + metavar="D", + help="dropout to apply to the input (after feat extr)", + ) + parser.add_argument( + "--dropout-features", + type=float, + metavar="D", + help="dropout to apply to the unmasked features (after feat extr)", + ) + parser.add_argument( + "--speech-extractor-mode", + type=str, + default="layer_norm", + choices=["default", "layer_norm"], + help="feature extractor norm", + ) + + parser.add_argument( + "--speech-conv-bias", + action="store_true", + help="include bias in speech conv encoder", + ) + + parser.add_argument( + "--conv-feature-layers", + default="[(512, 10, 5)] + [(512, 3, 2)] * 4 + [(512,2,2)] + [(512,2,2)]", + help="string describing convolutional feature extraction layers in form of a python list that contains [(dim, kernel_size, stride), ...]", + ) + + parser.add_argument( + "--speech-mask-length", + type=int, + help="repeat the mask indices multiple times", + ) + + parser.add_argument( + "--speech-mask-prob", + type=float, + help="probability of replacing a token with mask", + ) + + parser.add_argument( + "--speech-mask-selection", + type=str, + choices=["static", "uniform", "normal", "poisson"], + help="how to choose masks", + ) + + parser.add_argument( + "--speech-mask-other", + type=float, + help="stdev of the mask length in case of 'normal' selection strategy", + ) + + parser.add_argument( + "--speech-no-mask-overlap", + action="store_true", + help="whether to allow masks to overlap", + ) + + parser.add_argument( + "--speech-mask-min-space", + type=int, + help="min space between spans (if no overlap is enabled)", + ) + + parser.add_argument( + "--speech-mask-channel-length", + type=int, + help="repeat the mask indices multiple times", + ) + + parser.add_argument( + "--speech-mask-channel-prob", + type=float, + help="probability of replacing a token with mask", + ) + + parser.add_argument( + "--speech-mask-channel-selection", + type=str, + choices=["static", "uniform", "normal", "poisson"], + help="how to choose masks", + ) + + parser.add_argument( + "--speech-mask-channel-other", + type=float, + help="stdev of the mask length in case of 'normal' selection strategy", + ) + + parser.add_argument( + "--speech-no-mask-channel-overlap", + action="store_true", + help="whether to allow masks to overlap", + ) + + parser.add_argument( + "--no-scale-feature", + action="store_true", + help="no scale for the calculated features", + ) + + parser.add_argument( + "--speech-mask-channel-min-space", + type=int, + help="min space between spans (if no overlap is enabled)", + ) + + parser.add_argument( + "--feature-grad-mult", + type=float, + help="reset feature grad mult in wav2vec 2.0 to this", + ) + + # positional embeddings + parser.add_argument( + "--conv-pos", + type=int, + default=128, + help="number of filters for convolutional positional embeddings", + ) + + parser.add_argument( + "--conv-pos-groups", + type=int, + default=16, + help="number of groups for convolutional positional embedding", + ) + # model configures + parser.add_argument( + "--speech-encoder-layers", + type=int, + help="number of speech encoder layers", + ) + parser.add_argument( + "--text-encoder-layers", + type=int, + help="number of text encoder layers", + ) + + def __init__(self, args, alway_mask=False): + super().__init__(args) + self.args = args + self.dropout = args.dropout + self.embedding_dim = args.encoder_embed_dim + self.feat_scale = math.sqrt(args.encoder_embed_dim) + if args.no_scale_feature: + self.feat_scale = 1.0 + + subsample = ConvFeatureExtractionModel( + conv_layers=eval(args.conv_feature_layers), + dropout=0.0, + mode=args.speech_extractor_mode, # default, layer_norm + conv_bias=args.speech_conv_bias, + ) + feature_enc_layers = eval(args.conv_feature_layers) + self.subsample = subsample + self.feat_proj = ( + nn.Linear(feature_enc_layers[-1][0], self.embedding_dim) + if feature_enc_layers[-1][0] != self.embedding_dim + else None + ) + + self.feat_layer_norm = LayerNorm(feature_enc_layers[-1][0]) + + self.embed_positions = nn.Conv1d( + self.embedding_dim, + self.embedding_dim, + kernel_size=args.conv_pos, + padding=args.conv_pos // 2, + groups=args.conv_pos_groups, + ) + std = math.sqrt(4 / (args.conv_pos * self.embedding_dim)) + nn.init.normal_(self.embed_positions.weight, mean=0, std=std) + nn.init.constant_(self.embed_positions.bias, 0) + + self.embed_positions = nn.utils.weight_norm( + self.embed_positions, name="weight", dim=2 + ) + self.embed_positions = nn.Sequential( + self.embed_positions, SamePad(args.conv_pos), nn.GELU() + ) + + self.mask_prob = args.speech_mask_prob + self.mask_selection = args.speech_mask_selection + self.mask_other = args.speech_mask_other + self.mask_length = args.speech_mask_length + self.no_mask_overlap = args.speech_no_mask_overlap + self.mask_min_space = args.speech_mask_min_space + + self.mask_channel_prob = args.speech_mask_channel_prob + self.mask_channel_selection = args.speech_mask_channel_selection + self.mask_channel_other = args.speech_mask_channel_other + self.mask_channel_length = args.speech_mask_channel_length + self.no_mask_channel_overlap = args.speech_no_mask_channel_overlap + self.mask_channel_min_space = args.speech_mask_channel_min_space + + self.dropout_input = nn.Dropout(args.dropout_input) + self.dropout_features = nn.Dropout(args.dropout_features) + + self.feature_grad_mult = args.feature_grad_mult + + self.mask_emb = nn.Parameter( + torch.FloatTensor(args.encoder_embed_dim).uniform_() + ) + + self.layers = nn.ModuleList( + [TransformerEncoderLayer(args) for _ in range(args.encoder_layers)] + ) + self.layer_norm = LayerNorm(args.encoder_embed_dim) + self.normalize_before = args.encoder_normalize_before + self.alway_mask = alway_mask + + def apply_mask(self, x, padding_mask): + B, T, C = x.shape + if self.mask_prob > 0: + mask_indices = compute_mask_indices( + (B, T), + padding_mask, + self.mask_prob, + self.mask_length, + self.mask_selection, + self.mask_other, + min_masks=2, + no_overlap=self.no_mask_overlap, + min_space=self.mask_min_space, + ) + mask_indices = torch.from_numpy(mask_indices).to(x.device) + x[mask_indices] = self.mask_emb + else: + mask_indices = None + + if self.mask_channel_prob > 0: + mask_channel_indices = compute_mask_indices( + (B, C), + None, + self.mask_channel_prob, + self.mask_channel_length, + self.mask_channel_selection, + self.mask_channel_other, + no_overlap=self.no_mask_channel_overlap, + min_space=self.mask_channel_min_space, + ) + mask_channel_indices = ( + torch.from_numpy(mask_channel_indices) + .to(x.device) + .unsqueeze(1) + .expand(-1, T, -1) + ) + x[mask_channel_indices] = 0 + + return x, mask_indices + + def forward( + self, + src_tokens, + src_lengths, + return_all_hiddens=False, + padding_mask=None, + features_only=True, + ): + mask = self.training or self.alway_mask + if self.feature_grad_mult > 0 and self.training: + features = self.subsample(src_tokens) + if self.feature_grad_mult != 1.0: + features = GradMultiply.apply(features, self.feature_grad_mult) + else: + with torch.no_grad(): + features = self.subsample(src_tokens) + features = features.transpose(1, 2) + features = self.feat_layer_norm(features) + if self.feat_proj is not None: + features = self.feat_proj(features) + + if padding_mask is not None: + input_lengths = (1 - padding_mask.long()).sum(-1) + # apply conv formula to get real output_lengths + output_lengths = self._get_feat_extract_output_lengths(input_lengths) + + padding_mask = torch.zeros( + features.shape[:2], dtype=features.dtype, device=features.device + ) + + # these two operations makes sure that all values + # before the output lengths indices are attended to + padding_mask[ + ( + torch.arange(padding_mask.shape[0], device=padding_mask.device), + output_lengths - 1, + ) + ] = 1 + padding_mask = (1 - padding_mask.flip([-1]).cumsum(-1).flip([-1])).bool() + + features = self.feat_scale * features if self.feat_scale != 1.0 else features + unmasked_features = features.clone() + + features = self.dropout_input(features) + unmasked_features = self.dropout_features(unmasked_features) + if mask: + x, mask_indices = self.apply_mask(features, padding_mask) + else: + x = features + mask_indices = None + + def cal_transformer_layers(x, encoder_padding_mask, return_all_hiddens=False): + # x: B x T x C + positions = self.embed_positions(x.transpose(1, 2)).transpose(1, 2) + x = x + positions + if not self.normalize_before: + x = self.layer_norm(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + encoder_states = [] + for layer in self.layers: + x = layer(x, encoder_padding_mask) + if return_all_hiddens: + encoder_states.append(x) + if self.normalize_before: + x = self.layer_norm(x) + return x, encoder_states + + x, encoder_states = cal_transformer_layers(x, padding_mask, return_all_hiddens) + if features_only: + return { + "encoder_out": [x], # [T x B x C] + "encoder_padding_mask": [padding_mask] + if padding_mask is not None + else [], # B x T + "encoder_embedding": [], # + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], + "src_lengths": [], + "mask_indices": [mask_indices], + } + + x_unmasked = x + if self.mask_prob > 0 or self.mask_channel_prob > 0: + x_unmasked, _ = cal_transformer_layers(unmasked_features, padding_mask) + return { + "encoder_out": [x], # [T x B x C] + "encoder_unmasked_out": [x_unmasked], # [T x B x C] + "encoder_padding_mask": [padding_mask] + if padding_mask is not None + else [], # B x T + "encoder_embedding": [], # + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], + "src_lengths": [], + "mask_indices": [mask_indices] if mask_indices is not None else [], # B X T + } + + def reorder_encoder_out(self, encoder_out, new_order): + new_encoder_out = ( + [] + if len(encoder_out["encoder_out"]) == 0 + else [x.index_select(1, new_order) for x in encoder_out["encoder_out"]] + ) + + new_encoder_padding_mask = ( + [] + if len(encoder_out["encoder_padding_mask"]) == 0 + else [ + x.index_select(0, new_order) + for x in encoder_out["encoder_padding_mask"] + ] + ) + + new_encoder_embedding = ( + [] + if len(encoder_out["encoder_embedding"]) == 0 + else [ + x.index_select(0, new_order) for x in encoder_out["encoder_embedding"] + ] + ) + + encoder_states = encoder_out["encoder_states"] + if len(encoder_states) > 0: + for idx, state in enumerate(encoder_states): + encoder_states[idx] = state.index_select(1, new_order) + + return { + "encoder_out": new_encoder_out, # T x B x C + "encoder_padding_mask": new_encoder_padding_mask, # B x T + "encoder_embedding": new_encoder_embedding, # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], # B x T + "src_lengths": [], # B x 1 + } + + +class StackedSpeechWavTransformerEncoder(FairseqEncoder): + def __init__(self, speech_enc, text_enc_layers, text_layer_norm): + super().__init__(None) + self.speech_encoder = speech_enc + self.text_encoder_layers = text_enc_layers + self.final_layer_norm = text_layer_norm + + def forward( + self, + src_tokens, + src_lengths=None, + return_all_hiddens=False, + padding_mask=None, + features_only=True, + ): + + out = self.speech_encoder.forward( + src_tokens, + src_lengths, + return_all_hiddens, + padding_mask=padding_mask, + features_only=features_only, + ) + x = out["encoder_out"][0] + encoder_padding_mask = None + if len(out["encoder_padding_mask"]) > 0: + encoder_padding_mask = out["encoder_padding_mask"][0] + + def cal_text_layers(x, padding_mask, return_all_hiddens=False): + encoder_states = [] + for layer in self.text_encoder_layers: + x = layer(x, padding_mask) + if return_all_hiddens: + encoder_states.append(x) + if self.final_layer_norm is not None: + x = self.final_layer_norm(x) + return x, encoder_states + + x, encoder_states = cal_text_layers(x, encoder_padding_mask, return_all_hiddens) + if features_only: + return { + "encoder_out": [x], # T x B x C + "encoder_padding_mask": [encoder_padding_mask] + if encoder_padding_mask is not None + else [], # B x T + "encoder_embedding": [], # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], + "src_lengths": [], + } + + x_u = out["encoder_unmasked_out"][0] + x_u, _ = cal_text_layers(x_u, encoder_padding_mask) + + return { + "encoder_out": [x], # [T x B x C] + "encoder_unmasked_out": [x_u], # [T x B x C] + "encoder_padding_mask": [encoder_padding_mask] + if encoder_padding_mask is not None + else [], # B x T + "encoder_embedding": [], # + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], + "src_lengths": [], + "mask_indices": out["mask_indices"], # B X T + } + + def reorder_encoder_out(self, encoder_out, new_order): + return self.speech_encoder.reorder_encoder_out(encoder_out, new_order) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/utils.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/utils.py new file mode 100644 index 00000000..168b8bf1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/utils.py @@ -0,0 +1,563 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + + +import logging +from collections.abc import Iterable +from itertools import repeat +from typing import List, Optional, Tuple + +import torch +from torch import Tensor + + +# ------------------------------------------------------------------------------ +# assert_equal() +# ------------------------------------------------------------------------------ + + +def assert_equal(value1, value2, name1=None, name2=None): + """Asserts two values are equal otherwise raise an error.""" + + str_name1 = "" if name1 is None else "{} ".format(name1) + str_name2 = "" if name2 is None else "{} ".format(name2) + if value1 != value2: + str_value1 = "{}" if name1 is None else "({})" + str_value1 = str_value1.format(value1) + str_value2 = "{}" if name2 is None else "({})" + str_value2 = str_value2.format(value2) + raise ValueError( + "Expected {}{} == {}{}".format(str_name1, str_value1, str_name2, str_value2) + ) + + +def fill_config(config, key, value): + if value is not None: + if key not in config or config[key] is None: + config[key] = value + assert_equal(value, config[key], "value", f'config["{key}"]') + + +# ------------------------------------------------------------------------------ +# check_and_return_expected() +# ------------------------------------------------------------------------------ + + +def check_and_return_expected(value, undefined_value, expected_value, name=None): + """ + Return the expected value while checking if the given value is undefined or + equal to the expected value. + """ + if (undefined_value is None and value is None) or (undefined_value == value): + return expected_value + if value != expected_value: + str_name = "" if name is None else "{} ".format(name) + str_value = "{}" if name is None else "({})" + str_value = str_value.format(value) + raise ValueError( + "Expected {}{} == {}".format(str_name, str_value, expected_value) + ) + return expected_value + + +# ------------------------------------------------------------------------------ +# get_time_axis() +# ------------------------------------------------------------------------------ + + +def get_time_axis(layout): + """ + Extract the time axis from the layout, for example for breaking sequence into + segments. + """ + if layout in ["TB", "TBD"]: + return 0 + if layout in ["BT", "BTD"]: + return 1 + if layout in ["BCTD"]: + return 2 + raise ValueError("Unsupported layout = {}".format(layout)) + + +# ------------------------------------------------------------------------------ +# get_batch_axis() +# ------------------------------------------------------------------------------ + + +def get_batch_axis(layout): + """ + Extract the batch axis from the layout + """ + if layout in ["TB", "TBD"]: + return 1 + if layout in ["BT", "BTD", "BCTD"]: + return 0 + raise ValueError("Unsupported layout = {}".format(layout)) + + +# ------------------------------------------------------------------------------ +# monotonically_increasing_and_bounded() +# ------------------------------------------------------------------------------ + + +def monotonically_increasing_and_bounded(iterable, min=None, max=None): + """ + Check if the elements in the given iterable are monotonically increasing and + bounded by upper/lower bounds. + """ + if not isinstance(iterable, Iterable): + raise TypeError( + "Expected iterable to be of type Iterable, got ({})".format( + iterable.__class__.__name__ + ) + ) + for i in range(len(iterable)): + if min is not None and iterable[i] < min: + return False + if max is not None and iterable[i] > max: + return False + if i > 0 and iterable[i] <= iterable[i - 1]: + return False + return True + + +# ------------------------------------------------------------------------------ +# to_pair() +# ------------------------------------------------------------------------------ + + +def to_pair(value, name): + """Make a pair (of type tuple) of given value.""" + if isinstance(value, Iterable): + if len(value) != 2: + raise ValueError( + "Expected `{}` to have exactly 2 elements, got: ({})".format( + name, value + ) + ) + return value + return tuple(repeat(value, 2)) + + +# ------------------------------------------------------------------------------ +# infer_conv_output_attrs() +# ------------------------------------------------------------------------------ + + +# TODO(cfyeh): figure out if we can get `output_dim` without calling the module. +def infer_conv_output_attrs( + module, input_channels, input_dim, batch_size=1, max_length=8 +): + """Get output attributes of a module with input.""" + input = torch.randn(batch_size, input_channels, max_length, input_dim) + output = module(input) + output_channels = output.shape[1] + output_dim = output.shape[-1] + return output_channels, output_dim + + +# ------------------------------------------------------------------------------ +# NoOp +# ------------------------------------------------------------------------------ + + +class NoOp(torch.nn.Module): + """ + NoOp simply passes the input as the output. + """ + + def __init__(self): + super().__init__() + + def forward(self, input: Tensor) -> Tensor: + return input + + +# ------------------------------------------------------------------------------ +# Permute: a torch.nn.Module applies permutation on the input tensor. +# ------------------------------------------------------------------------------ + + +class Permute(torch.nn.Module): + def __init__(self, dims): + super().__init__() + self.dims = dims + + def forward(self, input: Tensor) -> Tensor: + return input.permute(self.dims).contiguous() + + +# ------------------------------------------------------------------------------ +# lengths_to_padding_mask() +# ------------------------------------------------------------------------------ + + +def lengths_to_padding_mask(lengths: Tensor) -> Tensor: + """Convert lengths of shape (B, ) to padding mask.""" + batch_size = lengths.shape[0] + max_length = int(torch.max(lengths).item()) + padding_mask = torch.arange( # [0, ..., T-1] + max_length, device=lengths.device, dtype=lengths.dtype + ).expand(batch_size, max_length) >= lengths.unsqueeze(1) + + return padding_mask + + +# ------------------------------------------------------------------------------ +# lengths_to_attention_mask() +# ------------------------------------------------------------------------------ + + +def lengths_to_attention_mask( + lengths: Tensor, + left_context: Optional[int] = None, + right_context: Optional[int] = None, +) -> Optional[Tensor]: + """ + Generate attention mask based on (lengths, left_context, right_context). + left_context is None means unlimited left context. + right_context is None means unlimited right context. + """ + + if left_context is None and right_context is None: + return None + + max_length = int(torch.max(lengths).item()) + + # For example, with `max_length` == 5, + # indices = tensor([ + # [ 0, 1, 2, 3, 4, 5], + # [-1, 0, 1, 2, 3, 4], + # [-2, -1, 0, 1, 2, 3], + # [-3, -2, -1, 0, 1, 2], + # [-4, -3, -2, -1, 0, 1], + # [-5, -4, -3, -2, -1, 0], + # ]) + + # In some cases the second torch.arange is created on cpu which causes a + # failure. Adding the device option to guard against it. + indices = torch.arange( + max_length, device=lengths.device, dtype=lengths.dtype + ).expand(max_length, max_length) - torch.arange( + max_length, device=lengths.device + ).view( + max_length, -1 + ) + + # For example, with `max_length` == 5, + # bool_mask = tensor([ + # [True, True, True, True, True], + # [True, True, True, True, True], + # [True, True, True, True, True], + # [True, True, True, True, True], + # [True, True, True, True, True], + # ]) + bool_mask = ( + torch.tensor([True]).to(device=lengths.device).expand(max_length, max_length) + ) + + # For example, with `max_length` == 5, left_context == 2 + # left_mask = tensor([ + # [ True, True, True, True, True], + # [ True, True, True, True, True], + # [ True, True, True, True, True], + # [False, True, True, True, True], + # [False, False, True, True, True], + # ]) + if left_context is not None: + left_mask = indices >= -left_context + bool_mask = bool_mask & left_mask + + # For example, with `max_length` == 5, right_context == 1 + # right_mask = tensor([ + # [True, True, False, False, False], + # [True, True, True, False, False], + # [True, True, True, True, False], + # [True, True, True, True, True], + # [True, True, True, True, True], + # ]) + if right_context is not None: + right_mask = indices <= right_context + bool_mask = bool_mask & right_mask + + bool_mask = (~bool_mask).to(device=lengths.device) + return bool_mask + + +# ------------------------------------------------------------------------------ +# infer_output_norm() +# ------------------------------------------------------------------------------ + + +def infer_output_norm(module, output_norm=None): + """ + Infer the output norm (string and module) needed on the module gvien desired + output normalization. + """ + if output_norm == module.output_norm(): + # output_norm already matches module.output_norm(). + return (None, NoOp()) + + if output_norm is None and module.output_norm() is not None: + logger = logging.getLogger("infer_output_norm()") + logger.warning( + "trying to set output_norm ({}) ".format(output_norm) + + "but got module.output_norm() ({}), ".format(module.output_norm()) + + "the combined output_norm() will be ({})".format(module.output_norm()) + ) + return (None, NoOp()) + + if output_norm == "log_softmax": + if module.output_norm() is not None: + raise ValueError( + "incompatible output_norm ({}) ".format(output_norm) + + "and module.output_norm() ({})".format(module.output_norm()) + ) + else: + return ("log_softmax", torch.nn.LogSoftmax(dim=-1)) + + if output_norm == "softmax": + if module.output_norm() is not None: + raise ValueError( + "incompatible output_norm ({}) ".format(output_norm) + + "and module.output_norm() ({})".format(module.output_norm()) + ) + else: + return ("softmax", torch.nn.Softmax(dim=-1)) + + raise ValueError( + "output_norm ({}) not in ".format(output_norm) + + "supported list = [None, softmax, log_softmax]" + ) + + +# ------------------------------------------------------------------------------ +# infer_channels_from_layout() +# ------------------------------------------------------------------------------ + + +def infer_channels_from_layout(layout, channels): + """Extract the number of channels from the layout.""" + if layout in ("TBD", "BTD"): + if channels is not None and channels != 1: + raise ValueError( + "Expected channels ({}) to be 1 for layout = {}".format( + channels, layout + ) + ) + if channels is None: + return 1 + return channels + + +# ------------------------------------------------------------------------------ +# pad_sequence() +# ------------------------------------------------------------------------------ + + +@torch.jit.export +def pad_sequence( + sequence: Tensor, + time_axis: int, + extra_left_context: int = 0, + extra_right_context: int = 0, +) -> Tensor: + """Pad extra left/right contexts to the sequence.""" + + if extra_left_context == 0 and extra_right_context == 0: + return sequence + + tensors_to_concat = [] + + if extra_left_context: + size = (extra_left_context,) + fill_value = 0 + indices = torch.full( + size=size, + fill_value=fill_value, + dtype=torch.long, + device=sequence.device, + ) + left_padding = torch.index_select(sequence, time_axis, indices) + tensors_to_concat.append(left_padding) + + tensors_to_concat.append(sequence) + + # NOTE(cfyeh): for efficiency reason we pad 0 instead of the last frame for + # extra right contexts. + if extra_right_context: + size = list(sequence.shape) + size[time_axis] = extra_right_context + right_padding = torch.zeros(size, dtype=sequence.dtype, device=sequence.device) + tensors_to_concat.append(right_padding) + + padded_sequence = torch.cat(tensors_to_concat, dim=time_axis) + return padded_sequence + + +# ------------------------------------------------------------------------------ +# sequence_to_segments() +# ------------------------------------------------------------------------------ + + +@torch.jit.export +def sequence_to_segments( + sequence: Tensor, + time_axis: int, + lengths: Tensor, + segment_size: Optional[int] = None, + extra_left_context: int = 0, + extra_right_context: int = 0, +) -> List[Tuple[Tensor, Tensor]]: + """Breaks sequence into segments.""" + + sequence = pad_sequence( + sequence=sequence, + time_axis=time_axis, + extra_left_context=extra_left_context, + extra_right_context=extra_right_context, + ) + + lengths = lengths + extra_left_context + extra_right_context + + segments: List[Tuple[Tensor, Tensor]] = [] + + if segment_size is None: + segments.append((sequence, lengths)) + return segments + + offset = 0 + end = sequence.shape[time_axis] + step = segment_size + size = extra_left_context + segment_size + extra_right_context + + while offset + extra_left_context + extra_right_context < end: + clamped_size = min(size, end - offset) + segment_lengths = torch.clamp(lengths - offset, min=0, max=clamped_size) + indices = torch.arange( + start=offset, + end=(offset + clamped_size), + step=1, + dtype=torch.long, + device=sequence.device, + ) + segment_tensor = torch.index_select(sequence, time_axis, indices) + segments.append((segment_tensor, segment_lengths)) + offset = offset + step + + return segments + + +# ------------------------------------------------------------------------------ +# segments_to_sequence() +# ------------------------------------------------------------------------------ + + +@torch.jit.export +def segments_to_sequence( + segments: List[Tuple[Tensor, Tensor]], time_axis: int +) -> Tuple[Tensor, Tensor]: + """Concatenate segments into a full sequence.""" + if len(segments) == 1: + return segments[0] + + tensors_to_concat: List[Tensor] = [] + lengths_to_stack: List[Tensor] = [] + + for tensor, lengths in segments: + tensors_to_concat.append(tensor) + lengths_to_stack.append(lengths) + + sequence = torch.cat(tensors_to_concat, dim=time_axis) + lengths = torch.stack(lengths_to_stack, dim=0) + lengths = torch.sum(lengths, dim=0) + + return sequence, lengths + + +def lengths_to_encoder_padding_mask(lengths, batch_first: bool = False): + """ + convert lengths (a 1-D Long/Int tensor) to 2-D binary tensor + + Args: + lengths: a (B, )-shaped tensor + batch_first: whether to return a (B, T) tensor + + Return: + max_length: maximum length of B sequences + encoder_padding_mask: a (max_length, B) binary mask, where + [t, b] = False for t < lengths[b] and True otherwise + + TODO: + kernelize this function if benchmarking shows this function is slow + """ + max_lengths = torch.max(lengths).item() + bsz = lengths.size(0) + encoder_padding_mask = torch.arange( + max_lengths + ).to( # a (T, ) tensor with [0, ..., T-1] + lengths.device + ).view( # move to the right device + 1, max_lengths + ).expand( # reshape to (1, T)-shaped tensor + bsz, -1 + ) > lengths.view( # expand to (B, T)-shaped tensor + bsz, 1 + ).expand( + -1, max_lengths + ) + if not batch_first: + return encoder_padding_mask.t(), max_lengths + else: + return encoder_padding_mask, max_lengths + + +# ------------------------------------------------------------------------------ +# attention suppression +# ------------------------------------------------------------------------------ + + +def attention_suppression(attention_weights: Tensor, scale: float): + # B, H, qlen, klen -> B, H, qlen, 1 + attention_prob = torch.nn.functional.softmax(attention_weights.float(), dim=-1) + attention_nozeros = attention_prob.to(torch.bool) + nozeros_sum = torch.sum(attention_nozeros.to(torch.float), dim=-1, keepdim=True) + + # For very sparse situation, we need get round about 0s + key_sum = torch.sum(attention_prob, dim=-1, keepdim=True) + + # nozeros_sum should > 1 + key_mean = key_sum / (nozeros_sum + 1e-8) + + # std calculation + dis = (attention_prob - key_mean) * (attention_prob - key_mean) + + # if attention_prob[i] < threshold, then dis_masked[i] = 0; for all i + dis_masked = torch.where( + attention_nozeros, dis, attention_prob.new_zeros(attention_prob.size()) + ) + + key_var = torch.sum(dis_masked, dim=-1, keepdim=True) + key_var = key_var / (nozeros_sum - 1.0 + 1e-8) + key_std = torch.sqrt(key_var) + key_thread = key_mean - scale * key_std + + # if attention_prob[i] >= key_thread, then attention_prob[i] + # , otherwise "-inf" + inf_tensor = attention_prob.new_zeros(attention_prob.size()).detach() + inf_tensor[:] = float("-inf") + attention_weights_float = torch.where( + attention_prob < key_thread, + inf_tensor, + attention_weights.float(), + ) + + return attention_weights_float.type_as(attention_weights) + + +def layer_norm_backward_hook(module, grad_input, grad_output, clamp_value): + return tuple(torch.clamp(v, min=-clamp_value, max=clamp_value) for v in grad_input) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/xm_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/xm_transformer.py new file mode 100644 index 00000000..b21ff823 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/speech_to_text/xm_transformer.py @@ -0,0 +1,747 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import copy +import logging +from typing import Dict, List, Optional, Tuple + +import numpy as np +import torch +import torch.nn as nn +from torch import Tensor + +from fairseq import checkpoint_utils, utils +from fairseq.data.data_utils import lengths_to_padding_mask +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + register_model, + register_model_architecture, +) +from fairseq.models.speech_to_text.hub_interface import S2THubInterface +from fairseq.models.transformer import Embedding, TransformerDecoder +from fairseq.models.wav2vec import Wav2VecEncoder +from fairseq.modules.layer_norm import LayerNorm + +logger = logging.getLogger(__name__) + + +class Conv1dAdaptor(nn.Module): + def __init__( + self, + in_dim, + out_dim, + n_layers=3, + kernel_size=3, + stride=2, + layerdrop=0.0, + layernorm=False, + proj=False, + ): + super().__init__() + self.proj, self.proj_ln = None, None + self.post_proj, self.post_proj_ln = None, None + if proj: + self.proj = nn.Sequential( + nn.Linear(in_dim, in_dim * 4), nn.ReLU(), nn.Linear(in_dim * 4, in_dim) + ) + self.proj_ln = LayerNorm(in_dim) + self.post_proj = nn.Sequential( + nn.Linear(out_dim, out_dim * 4), + nn.ReLU(), + nn.Linear(out_dim * 4, out_dim), + ) + self.post_proj_ln = LayerNorm(out_dim) + + self.layers = nn.ModuleList( + nn.Conv1d( + in_dim if i == 0 else out_dim, + out_dim * 2, + kernel_size, + stride=stride, + padding=kernel_size // 2, + ) + for i in range(n_layers) + ) + self.stride = stride + self.layerdrop = layerdrop + self.layernorm = LayerNorm(in_dim) if layernorm else None + + @classmethod + def add_args(cls, parser): + parser.add_argument("--adaptor-n-layers", type=int) + parser.add_argument("--adaptor-kernel-size", type=int) + parser.add_argument("--adaptor-stride", type=int) + parser.add_argument("--adaptor-layerdrop", type=float) + parser.add_argument("--adaptor-layernorm", action="store_true") + parser.add_argument("--adaptor-proj", action="store_true") + + def forward(self, x, padding_mask: Optional[torch.Tensor]): + if self.layernorm is not None: + x = self.layernorm(x) + + if self.proj is not None: + x = x + 0.5 * self.proj(x) + x = self.proj_ln(x) + + # T x B x C -> B x C x T + x = x.transpose(0, 1).transpose(1, 2) + out_lens = None + if padding_mask is not None: + out_lens = (~padding_mask).sum(1).float() + + for layer in self.layers: + layerdrop_prob = np.random.random() + if not self.training or (layerdrop_prob > self.layerdrop): + x = nn.functional.glu(layer(x), dim=1) + if padding_mask is not None: + out_lens = ((out_lens - 1) / self.stride + 1).floor() + # B x C x T -> T x B x C + x = x.transpose(1, 2).transpose(0, 1) + + if self.post_proj is not None: + x = x + 0.5 * self.post_proj(x) + x = self.post_proj_ln(x) + + out_padding_mask = None + if padding_mask is not None: + out_padding_mask = lengths_to_padding_mask(out_lens.long()) + return x, out_padding_mask + + +def add_wav2vec_asr_args(parser): + parser.add_argument("--w2v-path", help="path to wav2vec 2.0 model") + parser.add_argument( + "--no-pretrained-weights", + action="store_true", + help="if true, does not load pretrained weights", + ) + parser.add_argument( + "--dropout-input", + type=float, + metavar="D", + help="dropout to apply to the input (after feat extr)", + ) + parser.add_argument( + "--final-dropout", + type=float, + metavar="D", + help="dropout after transformer and before final projection", + ) + parser.add_argument( + "--apply-mask", action="store_true", help="apply masking during fine-tuning" + ) + parser.add_argument( + "--dropout", + type=float, + metavar="D", + help="dropout probability inside wav2vec 2.0 model", + ) + parser.add_argument( + "--attention-dropout", + type=float, + metavar="D", + help="dropout probability for attention weights inside wav2vec 2.0 model", + ) + parser.add_argument( + "--activation-dropout", + "--relu-dropout", + type=float, + metavar="D", + help="dropout probability after activation in FFN inside wav2vec 2.0 model", + ) + + parser.add_argument( + "--mask-length", type=int, help="repeat the mask indices multiple times" + ) + + parser.add_argument( + "--mask-prob", type=float, help="probability of replacing a token with mask" + ) + + parser.add_argument( + "--mask-selection", + type=str, + choices=["static", "uniform", "normal", "poisson"], + help="how to choose masks", + ) + + parser.add_argument( + "--mask-other", + type=float, + help="stdev of the mask length in case of 'normal' selection strategy", + ) + + parser.add_argument( + "--no-mask-overlap", + action="store_true", + help="whether to allow masks to overlap", + ) + + parser.add_argument( + "--mask-channel-length", type=int, help="repeat the mask indices multiple times" + ) + + parser.add_argument( + "--mask-channel-prob", + type=float, + help="probability of replacing a token with mask", + ) + + parser.add_argument( + "--mask-channel-selection", + type=str, + choices=["static", "uniform", "normal", "poisson"], + help="how to choose masks", + ) + + parser.add_argument( + "--mask-channel-other", + type=float, + help="stdev of the mask length in case of 'normal' selection strategy", + ) + + parser.add_argument( + "--no-mask-channel-overlap", + action="store_true", + help="whether to allow masks to overlap", + ) + + parser.add_argument( + "--freeze-finetune-updates", + default=0, + type=int, + help="dont finetune wav2vec for this many updates", + ) + + parser.add_argument( + "--feature-grad-mult", + default=None, + type=float, + help="reset feature grad mult in wav2vec 2.0 to this", + ) + + parser.add_argument( + "--layerdrop", + default=0.0, + type=float, + help="probability of dropping a layer in wav2vec 2.0", + ) + parser.add_argument( + "--max-positions", + type=int, + help="Max input positions to be used in the conformer encoder in wav2vec 2.0", + ) + + parser.add_argument("--encoder-proj", action="store_true") + + parser.add_argument("--w2v-args", default=None) + + parser.add_argument( + "--remove-weight-norm", + action="store_true", + help="if set, then the weight-norm (in one pos_conv layer) is removed from the model", + ) + + +def need_finetuning(ft_params, param_name): + if ft_params == "all": + return True + ft_params_list = ft_params.split(",") + for ft_param in ft_params_list: + if ft_param in param_name: + return True + return False + + +class Wav2VecEncoderWithAdaptor(FairseqEncoder): + def build_adaptor(self, args): + adaptor = None + if args.adaptor_n_layers > 0: + adaptor = Conv1dAdaptor( + args.decoder_embed_dim, + args.decoder_embed_dim, + n_layers=args.adaptor_n_layers, + kernel_size=args.adaptor_kernel_size, + stride=args.adaptor_stride, + layerdrop=args.adaptor_layerdrop, + layernorm=args.adaptor_layernorm, + proj=args.adaptor_proj, + ) + return adaptor + + def __init__(self, args): + super().__init__(None) + self.w2v_encoder = Wav2VecEncoder(args) + self.is_v0_arch = not args.adaptor_proj + self.w2v_proj_ln = None + if not self.is_v0_arch and self.w2v_encoder.proj is not None: + self.w2v_proj_ln = LayerNorm(args.decoder_embed_dim) + self.adaptor = self.build_adaptor(args) + + self.num_updates = 0 + self.freezing_updates = args.w2v_freezing_updates + self.finetuning_params = args.finetune_w2v_params + for k, p in self.w2v_encoder.w2v_model.named_parameters(): + p.requires_grad = need_finetuning(self.finetuning_params, k) + + @classmethod + def add_args(cls, parser): + add_wav2vec_asr_args(parser) + parser.add_argument( + "--normalize", + action="store_true", + help="if set, normalizes input to have 0 mean and unit variance", + ) + parser.add_argument( + "--finetune-w2v-params", + type=str, + metavar="STR", + help="comma-separated param strings to finetune.", + ) + parser.add_argument("--w2v-freezing-updates", type=int) + parser.add_argument("--load-pretrained-encoder-from", type=str, metavar="STR") + Conv1dAdaptor.add_args(parser) + + def set_num_updates(self, num_updates): + super().set_num_updates(num_updates) + self.num_updates = num_updates + + def forward(self, src_tokens, src_lengths=None, **kwargs): + if ( + self.freezing_updates is not None + and self.num_updates > self.freezing_updates + ): + for p in self.w2v_encoder.w2v_model.parameters(): + p.requires_grad = True + + padding_mask = lengths_to_padding_mask(src_lengths) + out = self.w2v_encoder.forward(src_tokens, padding_mask, tbc=True) + x, padding_mask = out["encoder_out"], out["padding_mask"] + if self.w2v_proj_ln is not None: + x = self.w2v_proj_ln(x) + + if self.adaptor is not None: + x, padding_mask = self.adaptor(x, padding_mask) + + return { + "encoder_out": [x], # T x B x C + "encoder_padding_mask": [] + if padding_mask is None + else [padding_mask], # B x T + "encoder_embedding": [], # B x T x C + "encoder_states": [], # List[T x B x C] + "src_tokens": [], + "src_lengths": [], + } + + def reorder_encoder_out(self, encoder_out, new_order): + new_encoder_out = ( + [] + if len(encoder_out["encoder_out"]) == 0 + else [x.index_select(1, new_order) for x in encoder_out["encoder_out"]] + ) + + new_encoder_padding_mask = ( + [] + if len(encoder_out["encoder_padding_mask"]) == 0 + else [ + x.index_select(0, new_order) + for x in encoder_out["encoder_padding_mask"] + ] + ) + + new_encoder_embedding = ( + [] + if len(encoder_out["encoder_embedding"]) == 0 + else [ + x.index_select(0, new_order) for x in encoder_out["encoder_embedding"] + ] + ) + + encoder_states = encoder_out["encoder_states"] + if len(encoder_states) > 0: + for idx, state in enumerate(encoder_states): + encoder_states[idx] = state.index_select(1, new_order) + + return { + "encoder_out": new_encoder_out, # T x B x C + "encoder_padding_mask": new_encoder_padding_mask, # B x T + "encoder_embedding": new_encoder_embedding, # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], # B x T + "src_lengths": [], # B x 1 + } + + +def add_decoder_args(parser): + parser.add_argument( + "--activation-fn", + type=str, + default="relu", + choices=utils.get_available_activation_fns(), + help="activation function to use", + ) + parser.add_argument( + "--decoder-dropout", type=float, metavar="D", help="dropout probability" + ) + parser.add_argument( + "--decoder-attention-dropout", + type=float, + metavar="D", + help="dropout probability for attention weights", + ) + parser.add_argument( + "--decoder-activation-dropout", + type=float, + metavar="D", + help="dropout probability after activation in FFN.", + ) + parser.add_argument( + "--decoder-embed-dim", type=int, metavar="N", help="decoder embedding dimension" + ) + parser.add_argument( + "--decoder-ffn-embed-dim", + type=int, + metavar="N", + help="decoder embedding dimension for FFN", + ) + parser.add_argument( + "--decoder-layers", type=int, metavar="N", help="num decoder layers" + ) + parser.add_argument( + "--decoder-attention-heads", + type=int, + metavar="N", + help="num decoder attention heads", + ) + parser.add_argument( + "--decoder-normalize-before", + action="store_true", + help="apply layernorm before each decoder block", + ) + parser.add_argument( + "--layernorm-embedding", action="store_true", help="add layernorm to embedding" + ) + parser.add_argument("--decoder-layerdrop", type=float, metavar="D") + parser.add_argument("--decoder-learned-pos", action="store_true") + parser.add_argument("--share-decoder-input-output-embed", action="store_true") + parser.add_argument( + "--no-scale-embedding", + action="store_true", + help="if True, dont scale embeddings", + ) + parser.add_argument( + "--load-pretrained-decoder-from", + type=str, + metavar="STR", + help="model to take decoder weights from (for initialization)", + ) + parser.add_argument( + "--finetune-decoder-params", + type=str, + metavar="STR", + help="comma-separated param strings to finetune.", + ) + + +def remove_weight_norm_from_model(model): + from functools import reduce + + layers_with_wn = [] + for param_name, _ in model.named_parameters(): + if param_name.endswith("_g"): + # retrieve the module with this param_name + module_names = param_name.split(".")[ + :-1 + ] # exclude the actual parameter name + wn_module = reduce(getattr, module_names, model) + layers_with_wn.append(wn_module) + for wn_module in layers_with_wn: + torch.nn.utils.remove_weight_norm(wn_module) + logger.warning(f"Weight norm removed from module with {wn_module}\n") + + +@register_model("xm_transformer") +class XMTransformerModel(FairseqEncoderDecoderModel): + @classmethod + def hub_models(cls): + base_url = "http://dl.fbaipublicfiles.com/fairseq/s2t" + model_ids = [ + "xm_transformer_600m-es_en-multi_domain", + "xm_transformer_600m-ru_en-multi_domain", + "xm_transformer_600m-fr_en-multi_domain", + "xm_transformer_600m-en_es-multi_domain", + "xm_transformer_600m-en_ru-multi_domain", + "xm_transformer_600m-en_fr-multi_domain", + "xm_transformer_600m-en_zh-multi_domain", + "xm_transformer_600m-en_ar-multi_domain", + "xm_transformer_600m-en_tr-multi_domain", + "xm_transformer_600m-en_vi-multi_domain", + "xm_transformer-21_en-xls_r_300m", + "xm_transformer-en_15-xls_r_300m", + "xm_transformer-21_en-xls_r_1b", + "xm_transformer-en_15-xls_r_1b", + "xm_transformer-21_en-xls_r_2b", + "xm_transformer-en_15-xls_r_2b", + "xm_transformer-22_16-xls_r_2b", + ] + return {i: f"{base_url}/{i}.tar.gz" for i in model_ids} + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + config_yaml="config.yaml", + **kwargs, + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + config_yaml=config_yaml, + **kwargs, + ) + return S2THubInterface(x["args"], x["task"], x["models"][0]) + + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + + @classmethod + def add_args(cls, parser): + """Add model-specific arguments to the parser.""" + Wav2VecEncoderWithAdaptor.add_args(parser) + add_decoder_args(parser) + parser.add_argument("--checkpoint-activations", action="store_true") + parser.add_argument("--offload-activations", action="store_true") + parser.add_argument("--min-params-to-wrap", type=int) + + @classmethod + def maybe_load_pretrained(cls, component, checkpoint: Optional[str] = None): + if checkpoint is None: + return component + + _load = checkpoint_utils.load_pretrained_component_from_model + try: + return _load(component, checkpoint) + except RuntimeError as e: + logger.warning(e) + return _load(component, checkpoint, strict=False) + + @classmethod + def build_encoder(cls, args): + _args = copy.deepcopy(args) + if not args.adaptor_proj and not args.encoder_proj: # V0 arch + state = checkpoint_utils.load_checkpoint_to_cpu(args.w2v_path) + if state.get("cfg") is not None: + encoder_embed_dim = state["cfg"]._content["model"]["encoder_embed_dim"] + elif state.get("args") is not None: + encoder_embed_dim = state["args"].encoder_embed_dim + else: + raise ValueError(f"Invalid config in {args.w2v_path}") + _args.decoder_embed_dim = encoder_embed_dim + del state + + encoder = Wav2VecEncoderWithAdaptor(_args) + encoder = cls.maybe_load_pretrained( + encoder, getattr(args, "load_pretrained_encoder_from", None) + ) + if args.remove_weight_norm: + # remove the wn for EMA usage + logger.warning("Removing weight norm from wav2vec encoder") + remove_weight_norm_from_model(encoder) + + return encoder + + @classmethod + def get_decoder_args_from_checkpoint(cls, ckpt_args): + assert "model" in ckpt_args, "Model args not found in checkpoint cfg!" + decoder_args = {} + for k, v in ckpt_args["model"].__dict__.items(): + if "decoder" in k: + decoder_args[k] = v + + return decoder_args + + @classmethod + def override_decoder_args(cls, cli_args, decoder_args_dict): + for k, v in decoder_args_dict.items(): + if v != getattr(cli_args, k, None): + logger.warning( + f"Overriding decoder arg {k}: from {getattr(cli_args, k, None)} to {v}" + ) + setattr(cli_args, k, v) + + return cli_args + + @classmethod + def build_decoder(cls, args, task, embed_tokens): + _args = copy.deepcopy(args) + if args.adaptor_proj or args.encoder_proj: # not V0 arch + _args.encoder_embed_dim = _args.decoder_embed_dim + _args.dropout = args.decoder_dropout + _args.attention_dropout = args.decoder_attention_dropout + _args.activation_dropout = args.decoder_activation_dropout + + decoder = TransformerDecoder(_args, task.target_dictionary, embed_tokens) + decoder = cls.maybe_load_pretrained( + decoder, getattr(args, "load_pretrained_decoder_from", None) + ) + + for k, p in decoder.named_parameters(): + p.requires_grad = need_finetuning(args.finetune_decoder_params, k) + return decoder + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present in older models + base_architecture(args) + if getattr(args, "load_pretrained_decoder_from", None): + ckpt = torch.load(getattr(args, "load_pretrained_decoder_from", None)) + decoder_args_dict = cls.get_decoder_args_from_checkpoint(ckpt["cfg"]) + args = cls.override_decoder_args(args, decoder_args_dict) + + def build_embedding(dictionary, embed_dim): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + return Embedding(num_embeddings, embed_dim, padding_idx) + + decoder_embed_tokens = build_embedding( + task.target_dictionary, args.decoder_embed_dim + ) + + encoder = cls.build_encoder(args) + decoder = cls.build_decoder(args, task, decoder_embed_tokens) + return cls(encoder, decoder) + + def get_normalized_probs( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + log_probs: bool, + sample: Optional[Dict[str, Tensor]] = None, + ): + return self.get_normalized_probs_scriptable(net_output, log_probs, sample) + + def forward(self, src_tokens, src_lengths, prev_output_tokens, **kwargs): + """ + The forward method inherited from the base class has a **kwargs + argument in its input, which is not supported in torchscript. This + method overwrites the forward method definition without **kwargs. + """ + encoder_out = self.encoder( + src_tokens=src_tokens, src_lengths=src_lengths, **kwargs + ) + decoder_out = self.decoder( + prev_output_tokens=prev_output_tokens, encoder_out=encoder_out + ) + return decoder_out + + def upgrade_state_dict(self, state_dict): + for k, _ in state_dict.items(): + if "adaptor.layers" in state_dict: + new = k.replace("adaptor.layers", "adaptor_layers") + state_dict[new] = state_dict[k] + del state_dict[k] + + +def set_default_w2v_encoder_args(args): + args.no_pretrained_weights = getattr(args, "no_pretrained_weights", False) + args.dropout_input = getattr(args, "dropout_input", 0) + args.final_dropout = getattr(args, "final_dropout", 0) + args.apply_mask = getattr(args, "apply_mask", False) + args.dropout = getattr(args, "dropout", 0) + args.attention_dropout = getattr(args, "attention_dropout", 0) + args.activation_dropout = getattr(args, "activation_dropout", 0) + args.encoder_proj = getattr(args, "encoder_proj", False) + args.remove_weight_norm = getattr(args, "remove_weight_norm", False) + + args.mask_length = getattr(args, "mask_length", 10) + args.mask_prob = getattr(args, "mask_prob", 0.5) + args.mask_selection = getattr(args, "mask_selection", "static") + args.mask_other = getattr(args, "mask_other", 0) + args.no_mask_overlap = getattr(args, "no_mask_overlap", False) + args.mask_channel_length = getattr(args, "mask_channel_length", 10) + args.mask_channel_prob = getattr(args, "mask_channel_prob", 0.5) + args.mask_channel_before = getattr(args, "mask_channel_before", False) + args.mask_channel_selection = getattr(args, "mask_channel_selection", "static") + args.mask_channel_other = getattr(args, "mask_channel_other", 0) + args.no_mask_channel_overlap = getattr(args, "no_mask_channel_overlap", False) + + args.freeze_finetune_updates = getattr(args, "freeze_finetune_updates", 0) + args.feature_grad_mult = 0.1 + args.layerdrop = getattr(args, "layerdrop", 0.0) + + args.normalize = getattr(args, "normalize", False) + args.finetune_w2v_params = getattr(args, "finetune_w2v_params", "all") + args.w2v_freezing_updates = getattr(args, "w2v_freezing_updates", None) + + +def set_default_adaptor_args(args): + args.adaptor_n_layers = getattr(args, "adaptor_n_layers", 3) + args.adaptor_kernel_size = getattr(args, "adaptor_kernel_size", 3) + args.adaptor_stride = getattr(args, "adaptor_stride", 2) + args.adaptor_layerdrop = getattr(args, "adaptor_layerdrop", 0.0) + args.adaptor_layernorm = getattr(args, "adaptor_layernorm", False) + args.adaptor_proj = getattr(args, "adaptor_proj", False) + + +def set_default_transformer_decoder_args(args): + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 1024) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 4 * 1024) + args.decoder_layers = getattr(args, "decoder_layers", 12) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 16) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.decoder_layerdrop = getattr(args, "decoder_layerdrop", 0.0) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.decoder_attention_dropout = getattr(args, "decoder_attention_dropout", 0.0) + args.decoder_activation_dropout = getattr(args, "decoder_activation_dropout", 0.0) + args.decoder_dropout = getattr(args, "decoder_dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + args.quant_noise_pq = getattr(args, "quant_noise_pq", 0) + args.layernorm_embedding = getattr(args, "layernorm_embedding", False) + + args.activation_fn = getattr(args, "activation_fn", "gelu") + args.pooler_activation_fn = getattr(args, "pooler_activation_fn", "tanh") + args.pooler_dropout = getattr(args, "pooler_dropout", 0.0) + + args.finetune_decoder_params = getattr(args, "finetune_decoder_params", "all") + + +def set_default_general_args(args): + args.checkpoint_activations = getattr(args, "checkpoint_activations", False) + args.offload_activations = getattr(args, "offload_activations", False) + args.min_params_to_wrap = getattr(args, "min_params_to_wrap", int(1e8)) + args.max_positions = getattr(args, "max_positions", 3000) + + +@register_model_architecture(model_name="xm_transformer", arch_name="xm_transformer") +def base_architecture(args): + set_default_general_args(args) + set_default_w2v_encoder_args(args) + set_default_adaptor_args(args) + set_default_transformer_decoder_args(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/__init__.py new file mode 100644 index 00000000..652fee0d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/__init__.py @@ -0,0 +1,8 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .tacotron2 import * # noqa +from .tts_transformer import * # noqa +from .fastspeech2 import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/codehifigan.py b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/codehifigan.py new file mode 100644 index 00000000..d1574dd6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/codehifigan.py @@ -0,0 +1,95 @@ +from argparse import Namespace +import torch +import torch.nn as nn + +from fairseq.models.text_to_speech.fastspeech2 import VariancePredictor +from fairseq.models.text_to_speech.hifigan import Generator + + +class CodeGenerator(Generator): + def __init__(self, cfg): + super().__init__(cfg) + self.dict = nn.Embedding(cfg["num_embeddings"], cfg["embedding_dim"]) + self.multispkr = cfg.get("multispkr", None) + self.embedder = cfg.get("embedder_params", None) + + if self.multispkr and not self.embedder: + self.spkr = nn.Embedding(cfg.get("num_speakers", 200), cfg["embedding_dim"]) + elif self.embedder: + self.spkr = nn.Linear(cfg.get("embedder_dim", 256), cfg["embedding_dim"]) + + self.dur_predictor = None + if cfg.get("dur_predictor_params", None): + self.dur_predictor = VariancePredictor( + Namespace(**cfg["dur_predictor_params"]) + ) + + self.f0 = cfg.get("f0", None) + n_f0_bin = cfg.get("f0_quant_num_bin", 0) + self.f0_quant_embed = ( + None if n_f0_bin <= 0 else nn.Embedding(n_f0_bin, cfg["embedding_dim"]) + ) + + @staticmethod + def _upsample(signal, max_frames): + if signal.dim() == 3: + bsz, channels, cond_length = signal.size() + elif signal.dim() == 2: + signal = signal.unsqueeze(2) + bsz, channels, cond_length = signal.size() + else: + signal = signal.view(-1, 1, 1) + bsz, channels, cond_length = signal.size() + + signal = signal.unsqueeze(3).repeat(1, 1, 1, max_frames // cond_length) + + # pad zeros as needed (if signal's shape does not divide completely with max_frames) + reminder = (max_frames - signal.shape[2] * signal.shape[3]) // signal.shape[3] + if reminder > 0: + raise NotImplementedError( + "Padding condition signal - misalignment between condition features." + ) + + signal = signal.view(bsz, channels, max_frames) + return signal + + def forward(self, **kwargs): + x = self.dict(kwargs["code"]).transpose(1, 2) + + if self.dur_predictor and kwargs.get("dur_prediction", False): + assert x.size(0) == 1, "only support single sample" + log_dur_pred = self.dur_predictor(x.transpose(1, 2)) + dur_out = torch.clamp( + torch.round((torch.exp(log_dur_pred) - 1)).long(), min=1 + ) + # B x C x T + x = torch.repeat_interleave(x, dur_out.view(-1), dim=2) + + if self.f0: + if self.f0_quant_embed: + kwargs["f0"] = self.f0_quant_embed(kwargs["f0"].long()).transpose(1, 2) + else: + kwargs["f0"] = kwargs["f0"].unsqueeze(1) + + if x.shape[-1] < kwargs["f0"].shape[-1]: + x = self._upsample(x, kwargs["f0"].shape[-1]) + elif x.shape[-1] > kwargs["f0"].shape[-1]: + kwargs["f0"] = self._upsample(kwargs["f0"], x.shape[-1]) + x = torch.cat([x, kwargs["f0"]], dim=1) + + if self.multispkr: + assert ( + "spkr" in kwargs + ), 'require "spkr" input for multispeaker CodeHiFiGAN vocoder' + spkr = self.spkr(kwargs["spkr"]).transpose(1, 2) + spkr = self._upsample(spkr, x.shape[-1]) + x = torch.cat([x, spkr], dim=1) + + for k, feat in kwargs.items(): + if k in ["spkr", "code", "f0", "dur_prediction"]: + continue + + feat = self._upsample(feat, x.shape[-1]) + x = torch.cat([x, feat], dim=1) + + return super().forward(x) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/fastspeech2.py b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/fastspeech2.py new file mode 100644 index 00000000..fb2d0df3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/fastspeech2.py @@ -0,0 +1,448 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch +from torch import nn + +from fairseq import utils +from fairseq.data.data_utils import lengths_to_padding_mask +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderModel, + register_model, + register_model_architecture, +) +from fairseq.models.text_to_speech.hub_interface import TTSHubInterface +from fairseq.models.text_to_speech.tacotron2 import Postnet +from fairseq.modules import ( + FairseqDropout, + LayerNorm, + MultiheadAttention, + PositionalEmbedding, +) + +logger = logging.getLogger(__name__) + + +def model_init(m): + if isinstance(m, nn.Conv1d): + nn.init.xavier_uniform_(m.weight, torch.nn.init.calculate_gain("relu")) + + +def Embedding(num_embeddings, embedding_dim, padding_idx=None): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + nn.init.normal_(m.weight, mean=0, std=embedding_dim**-0.5) + return m + + +class PositionwiseFeedForward(nn.Module): + def __init__(self, in_dim, hidden_dim, kernel_size, dropout): + super().__init__() + self.ffn = nn.Sequential( + nn.Conv1d( + in_dim, + hidden_dim, + kernel_size=kernel_size, + padding=(kernel_size - 1) // 2, + ), + nn.ReLU(), + nn.Conv1d( + hidden_dim, + in_dim, + kernel_size=kernel_size, + padding=(kernel_size - 1) // 2, + ), + ) + self.layer_norm = LayerNorm(in_dim) + self.dropout = self.dropout_module = FairseqDropout( + p=dropout, module_name=self.__class__.__name__ + ) + + def forward(self, x): + # B x T x C + residual = x + x = self.ffn(x.transpose(1, 2)).transpose(1, 2) + x = self.dropout(x) + return self.layer_norm(x + residual) + + +class FFTLayer(torch.nn.Module): + def __init__( + self, embed_dim, n_heads, hidden_dim, kernel_size, dropout, attention_dropout + ): + super().__init__() + self.self_attn = MultiheadAttention( + embed_dim, n_heads, dropout=attention_dropout, self_attention=True + ) + self.layer_norm = LayerNorm(embed_dim) + self.ffn = PositionwiseFeedForward( + embed_dim, hidden_dim, kernel_size, dropout=dropout + ) + + def forward(self, x, padding_mask=None): + # B x T x C + residual = x + x = x.transpose(0, 1) + x, _ = self.self_attn( + query=x, key=x, value=x, key_padding_mask=padding_mask, need_weights=False + ) + x = x.transpose(0, 1) + x = self.layer_norm(x + residual) + return self.ffn(x) + + +class LengthRegulator(nn.Module): + def forward(self, x, durations): + # x: B x T x C + out_lens = durations.sum(dim=1) + max_len = out_lens.max() + bsz, seq_len, dim = x.size() + out = x.new_zeros((bsz, max_len, dim)) + + for b in range(bsz): + indices = [] + for t in range(seq_len): + indices.extend([t] * utils.item(durations[b, t])) + indices = torch.tensor(indices, dtype=torch.long).to(x.device) + out_len = utils.item(out_lens[b]) + out[b, :out_len] = x[b].index_select(0, indices) + + return out, out_lens + + +class VariancePredictor(nn.Module): + def __init__(self, args): + super().__init__() + self.conv1 = nn.Sequential( + nn.Conv1d( + args.encoder_embed_dim, + args.var_pred_hidden_dim, + kernel_size=args.var_pred_kernel_size, + padding=(args.var_pred_kernel_size - 1) // 2, + ), + nn.ReLU(), + ) + self.ln1 = nn.LayerNorm(args.var_pred_hidden_dim) + self.dropout_module = FairseqDropout( + p=args.var_pred_dropout, module_name=self.__class__.__name__ + ) + self.conv2 = nn.Sequential( + nn.Conv1d( + args.var_pred_hidden_dim, + args.var_pred_hidden_dim, + kernel_size=args.var_pred_kernel_size, + padding=1, + ), + nn.ReLU(), + ) + self.ln2 = nn.LayerNorm(args.var_pred_hidden_dim) + self.proj = nn.Linear(args.var_pred_hidden_dim, 1) + + def forward(self, x): + # Input: B x T x C; Output: B x T + x = self.conv1(x.transpose(1, 2)).transpose(1, 2) + x = self.dropout_module(self.ln1(x)) + x = self.conv2(x.transpose(1, 2)).transpose(1, 2) + x = self.dropout_module(self.ln2(x)) + return self.proj(x).squeeze(dim=2) + + +class VarianceAdaptor(nn.Module): + def __init__(self, args): + super().__init__() + self.args = args + self.length_regulator = LengthRegulator() + self.duration_predictor = VariancePredictor(args) + self.pitch_predictor = VariancePredictor(args) + self.energy_predictor = VariancePredictor(args) + + n_bins, steps = self.args.var_pred_n_bins, self.args.var_pred_n_bins - 1 + self.pitch_bins = torch.linspace(args.pitch_min, args.pitch_max, steps) + self.embed_pitch = Embedding(n_bins, args.encoder_embed_dim) + self.energy_bins = torch.linspace(args.energy_min, args.energy_max, steps) + self.embed_energy = Embedding(n_bins, args.encoder_embed_dim) + + def get_pitch_emb(self, x, tgt=None, factor=1.0): + out = self.pitch_predictor(x) + bins = self.pitch_bins.to(x.device) + if tgt is None: + out = out * factor + emb = self.embed_pitch(torch.bucketize(out, bins)) + else: + emb = self.embed_pitch(torch.bucketize(tgt, bins)) + return out, emb + + def get_energy_emb(self, x, tgt=None, factor=1.0): + out = self.energy_predictor(x) + bins = self.energy_bins.to(x.device) + if tgt is None: + out = out * factor + emb = self.embed_energy(torch.bucketize(out, bins)) + else: + emb = self.embed_energy(torch.bucketize(tgt, bins)) + return out, emb + + def forward( + self, + x, + padding_mask, + durations=None, + pitches=None, + energies=None, + d_factor=1.0, + p_factor=1.0, + e_factor=1.0, + ): + # x: B x T x C + log_dur_out = self.duration_predictor(x) + dur_out = torch.clamp( + torch.round((torch.exp(log_dur_out) - 1) * d_factor).long(), min=0 + ) + dur_out.masked_fill_(padding_mask, 0) + + pitch_out, pitch_emb = self.get_pitch_emb(x, pitches, p_factor) + x = x + pitch_emb + energy_out, energy_emb = self.get_energy_emb(x, energies, e_factor) + x = x + energy_emb + + x, out_lens = self.length_regulator( + x, dur_out if durations is None else durations + ) + + return x, out_lens, log_dur_out, pitch_out, energy_out + + +class FastSpeech2Encoder(FairseqEncoder): + def __init__(self, args, src_dict, embed_speaker): + super().__init__(src_dict) + self.args = args + self.padding_idx = src_dict.pad() + self.n_frames_per_step = args.n_frames_per_step + self.out_dim = args.output_frame_dim * args.n_frames_per_step + + self.embed_speaker = embed_speaker + self.spk_emb_proj = None + if embed_speaker is not None: + self.spk_emb_proj = nn.Linear( + args.encoder_embed_dim + args.speaker_embed_dim, args.encoder_embed_dim + ) + + self.dropout_module = FairseqDropout( + p=args.dropout, module_name=self.__class__.__name__ + ) + self.embed_tokens = Embedding( + len(src_dict), args.encoder_embed_dim, padding_idx=self.padding_idx + ) + + self.embed_positions = PositionalEmbedding( + args.max_source_positions, args.encoder_embed_dim, self.padding_idx + ) + self.pos_emb_alpha = nn.Parameter(torch.ones(1)) + self.dec_pos_emb_alpha = nn.Parameter(torch.ones(1)) + + self.encoder_fft_layers = nn.ModuleList( + FFTLayer( + args.encoder_embed_dim, + args.encoder_attention_heads, + args.fft_hidden_dim, + args.fft_kernel_size, + dropout=args.dropout, + attention_dropout=args.attention_dropout, + ) + for _ in range(args.encoder_layers) + ) + + self.var_adaptor = VarianceAdaptor(args) + + self.decoder_fft_layers = nn.ModuleList( + FFTLayer( + args.decoder_embed_dim, + args.decoder_attention_heads, + args.fft_hidden_dim, + args.fft_kernel_size, + dropout=args.dropout, + attention_dropout=args.attention_dropout, + ) + for _ in range(args.decoder_layers) + ) + + self.out_proj = nn.Linear(args.decoder_embed_dim, self.out_dim) + + self.postnet = None + if args.add_postnet: + self.postnet = Postnet( + self.out_dim, + args.postnet_conv_dim, + args.postnet_conv_kernel_size, + args.postnet_layers, + args.postnet_dropout, + ) + + self.apply(model_init) + + def forward( + self, + src_tokens, + src_lengths=None, + speaker=None, + durations=None, + pitches=None, + energies=None, + **kwargs, + ): + x = self.embed_tokens(src_tokens) + + enc_padding_mask = src_tokens.eq(self.padding_idx) + x += self.pos_emb_alpha * self.embed_positions(enc_padding_mask) + x = self.dropout_module(x) + + for layer in self.encoder_fft_layers: + x = layer(x, enc_padding_mask) + + if self.embed_speaker is not None: + bsz, seq_len, _ = x.size() + emb = self.embed_speaker(speaker).expand(bsz, seq_len, -1) + x = self.spk_emb_proj(torch.cat([x, emb], dim=2)) + + x, out_lens, log_dur_out, pitch_out, energy_out = self.var_adaptor( + x, enc_padding_mask, durations, pitches, energies + ) + + dec_padding_mask = lengths_to_padding_mask(out_lens) + x += self.dec_pos_emb_alpha * self.embed_positions(dec_padding_mask) + for layer in self.decoder_fft_layers: + x = layer(x, dec_padding_mask) + + x = self.out_proj(x) + x_post = None + if self.postnet is not None: + x_post = x + self.postnet(x) + return x, x_post, out_lens, log_dur_out, pitch_out, energy_out + + +@register_model("fastspeech2") +class FastSpeech2Model(FairseqEncoderModel): + """ + Implementation for https://arxiv.org/abs/2006.04558 + """ + + NON_AUTOREGRESSIVE = True + + @classmethod + def hub_models(cls): + base_url = "http://dl.fbaipublicfiles.com/fairseq/s2" + model_ids = [ + "fastspeech2-en-ljspeech", + "fastspeech2-en-200_speaker-cv4", + ] + return {i: f"{base_url}/{i}.tar.gz" for i in model_ids} + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + config_yaml="config.yaml", + vocoder: str = "griffin_lim", + fp16: bool = False, + **kwargs, + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + config_yaml=config_yaml, + vocoder=vocoder, + fp16=fp16, + **kwargs, + ) + return TTSHubInterface(x["args"], x["task"], x["models"][0]) + + @staticmethod + def add_args(parser): + parser.add_argument("--dropout", type=float) + parser.add_argument("--output-frame-dim", type=int) + parser.add_argument("--speaker-embed-dim", type=int) + # FFT blocks + parser.add_argument("--fft-hidden-dim", type=int) + parser.add_argument("--fft-kernel-size", type=int) + parser.add_argument("--attention-dropout", type=float) + parser.add_argument("--encoder-layers", type=int) + parser.add_argument("--encoder-embed-dim", type=int) + parser.add_argument("--encoder-attention-heads", type=int) + parser.add_argument("--decoder-layers", type=int) + parser.add_argument("--decoder-embed-dim", type=int) + parser.add_argument("--decoder-attention-heads", type=int) + # variance predictor + parser.add_argument("--var-pred-n-bins", type=int) + parser.add_argument("--var-pred-hidden-dim", type=int) + parser.add_argument("--var-pred-kernel-size", type=int) + parser.add_argument("--var-pred-dropout", type=float) + # postnet + parser.add_argument("--add-postnet", action="store_true") + parser.add_argument("--postnet-dropout", type=float) + parser.add_argument("--postnet-layers", type=int) + parser.add_argument("--postnet-conv-dim", type=int) + parser.add_argument("--postnet-conv-kernel-size", type=int) + + def __init__(self, encoder, args, src_dict): + super().__init__(encoder) + self._num_updates = 0 + + out_dim = args.output_frame_dim * args.n_frames_per_step + self.ctc_proj = None + if getattr(args, "ctc_weight", 0.0) > 0.0: + self.ctc_proj = nn.Linear(out_dim, len(src_dict)) + + @classmethod + def build_model(cls, args, task): + embed_speaker = task.get_speaker_embeddings(args) + encoder = FastSpeech2Encoder(args, task.src_dict, embed_speaker) + return cls(encoder, args, task.src_dict) + + def set_num_updates(self, num_updates): + super().set_num_updates(num_updates) + self._num_updates = num_updates + + def get_normalized_probs(self, net_output, log_probs, sample=None): + logits = self.ctc_proj(net_output[0]) + if log_probs: + return utils.log_softmax(logits.float(), dim=-1) + else: + return utils.softmax(logits.float(), dim=-1) + + +@register_model_architecture("fastspeech2", "fastspeech2") +def base_architecture(args): + args.dropout = getattr(args, "dropout", 0.2) + args.output_frame_dim = getattr(args, "output_frame_dim", 80) + args.speaker_embed_dim = getattr(args, "speaker_embed_dim", 64) + # FFT blocks + args.fft_hidden_dim = getattr(args, "fft_hidden_dim", 1024) + args.fft_kernel_size = getattr(args, "fft_kernel_size", 9) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.encoder_layers = getattr(args, "encoder_layers", 4) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 256) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 2) + args.decoder_layers = getattr(args, "decoder_layers", 4) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 256) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 2) + # variance predictor + args.var_pred_n_bins = getattr(args, "var_pred_n_bins", 256) + args.var_pred_hidden_dim = getattr(args, "var_pred_hidden_dim", 256) + args.var_pred_kernel_size = getattr(args, "var_pred_kernel_size", 3) + args.var_pred_dropout = getattr(args, "var_pred_dropout", 0.5) + # postnet + args.add_postnet = getattr(args, "add_postnet", False) + args.postnet_dropout = getattr(args, "postnet_dropout", 0.5) + args.postnet_layers = getattr(args, "postnet_layers", 5) + args.postnet_conv_dim = getattr(args, "postnet_conv_dim", 512) + args.postnet_conv_kernel_size = getattr(args, "postnet_conv_kernel_size", 5) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/hifigan.py b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/hifigan.py new file mode 100644 index 00000000..a852beef --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/hifigan.py @@ -0,0 +1,179 @@ +import torch +import torch.nn as nn +import torch.nn.functional as F +from torch.nn import Conv1d, ConvTranspose1d +from torch.nn.utils import remove_weight_norm, weight_norm + +LRELU_SLOPE = 0.1 + + +def init_weights(m, mean=0.0, std=0.01): + classname = m.__class__.__name__ + if classname.find("Conv") != -1: + m.weight.data.normal_(mean, std) + + +def get_padding(kernel_size, dilation=1): + return (kernel_size * dilation - dilation) // 2 + + +class ResBlock(torch.nn.Module): + def __init__(self, channels, kernel_size=3, dilation=(1, 3, 5)): + super(ResBlock, self).__init__() + self.convs1 = nn.ModuleList( + [ + weight_norm( + Conv1d( + channels, + channels, + kernel_size, + 1, + dilation=dilation[0], + padding=get_padding(kernel_size, dilation[0]), + ) + ), + weight_norm( + Conv1d( + channels, + channels, + kernel_size, + 1, + dilation=dilation[1], + padding=get_padding(kernel_size, dilation[1]), + ) + ), + weight_norm( + Conv1d( + channels, + channels, + kernel_size, + 1, + dilation=dilation[2], + padding=get_padding(kernel_size, dilation[2]), + ) + ), + ] + ) + self.convs1.apply(init_weights) + + self.convs2 = nn.ModuleList( + [ + weight_norm( + Conv1d( + channels, + channels, + kernel_size, + 1, + dilation=1, + padding=get_padding(kernel_size, 1), + ) + ), + weight_norm( + Conv1d( + channels, + channels, + kernel_size, + 1, + dilation=1, + padding=get_padding(kernel_size, 1), + ) + ), + weight_norm( + Conv1d( + channels, + channels, + kernel_size, + 1, + dilation=1, + padding=get_padding(kernel_size, 1), + ) + ), + ] + ) + self.convs2.apply(init_weights) + + def forward(self, x): + for c1, c2 in zip(self.convs1, self.convs2): + xt = F.leaky_relu(x, LRELU_SLOPE) + xt = c1(xt) + xt = F.leaky_relu(xt, LRELU_SLOPE) + xt = c2(xt) + x = xt + x + return x + + def remove_weight_norm(self): + for layer in self.convs1: + remove_weight_norm(layer) + for layer in self.convs2: + remove_weight_norm(layer) + + +class Generator(torch.nn.Module): + def __init__(self, cfg): + super(Generator, self).__init__() + self.num_kernels = len(cfg["resblock_kernel_sizes"]) + self.num_upsamples = len(cfg["upsample_rates"]) + self.conv_pre = weight_norm( + Conv1d( + cfg.get("model_in_dim", 80), + cfg["upsample_initial_channel"], + 7, + 1, + padding=3, + ) + ) + + self.ups = nn.ModuleList() + for i, (u, k) in enumerate( + zip(cfg["upsample_rates"], cfg["upsample_kernel_sizes"]) + ): + self.ups.append( + weight_norm( + ConvTranspose1d( + cfg["upsample_initial_channel"] // (2**i), + cfg["upsample_initial_channel"] // (2 ** (i + 1)), + k, + u, + padding=(k - u) // 2, + ) + ) + ) + + self.resblocks = nn.ModuleList() + for i in range(len(self.ups)): + ch = cfg["upsample_initial_channel"] // (2 ** (i + 1)) + for k, d in zip( + cfg["resblock_kernel_sizes"], cfg["resblock_dilation_sizes"] + ): + self.resblocks.append(ResBlock(ch, k, d)) + + self.conv_post = weight_norm(Conv1d(ch, 1, 7, 1, padding=3)) + self.ups.apply(init_weights) + self.conv_post.apply(init_weights) + + def forward(self, x): + x = self.conv_pre(x) + for i in range(self.num_upsamples): + x = F.leaky_relu(x, LRELU_SLOPE) + x = self.ups[i](x) + xs = None + for j in range(self.num_kernels): + if xs is None: + xs = self.resblocks[i * self.num_kernels + j](x) + else: + xs += self.resblocks[i * self.num_kernels + j](x) + x = xs / self.num_kernels + x = F.leaky_relu(x) + x = self.conv_post(x) + x = torch.tanh(x) + + return x + + def remove_weight_norm(self): + print("Removing weight norm...") + for layer in self.ups: + remove_weight_norm(layer) + for layer in self.resblocks: + layer.remove_weight_norm() + remove_weight_norm(self.conv_pre) + remove_weight_norm(self.conv_post) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/hub_interface.py b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/hub_interface.py new file mode 100644 index 00000000..26c7ccac --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/hub_interface.py @@ -0,0 +1,139 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import random +from pathlib import Path +from typing import Dict, Optional, Tuple + +import torch +import torch.nn as nn + +logger = logging.getLogger(__name__) + + +class TTSHubInterface(nn.Module): + def __init__(self, cfg, task, model): + super().__init__() + self.cfg = cfg + self.task = task + self.model = model + self.model.eval() + + self.update_cfg_with_data_cfg(self.cfg, self.task.data_cfg) + self.generator = self.task.build_generator([self.model], self.cfg) + + @classmethod + def phonemize( + cls, + text: str, + lang: Optional[str], + phonemizer: Optional[str] = None, + preserve_punct: bool = False, + to_simplified_zh: bool = False, + ): + if to_simplified_zh: + import hanziconv + + text = hanziconv.HanziConv.toSimplified(text) + + if phonemizer == "g2p": + import g2p_en + + g2p = g2p_en.G2p() + if preserve_punct: + return " ".join("|" if p == " " else p for p in g2p(text)) + else: + res = [{",": "sp", ";": "sp"}.get(p, p) for p in g2p(text)] + return " ".join(p for p in res if p.isalnum()) + if phonemizer == "g2pc": + import g2pc + + g2p = g2pc.G2pC() + return " ".join([w[3] for w in g2p(text)]) + elif phonemizer == "ipa": + assert lang is not None + import phonemizer + from phonemizer.separator import Separator + + lang_map = {"en": "en-us", "fr": "fr-fr"} + return phonemizer.phonemize( + text, + backend="espeak", + language=lang_map.get(lang, lang), + separator=Separator(word="| ", phone=" "), + ) + else: + return text + + @classmethod + def tokenize(cls, text: str, tkn_cfg: Dict[str, str]): + sentencepiece_model = tkn_cfg.get("sentencepiece_model", None) + if sentencepiece_model is not None: + assert Path(sentencepiece_model).exists() + import sentencepiece as sp + + spm = sp.SentencePieceProcessor() + spm.Load(sentencepiece_model) + return " ".join(spm.Encode(text, out_type=str)) + else: + return text + + @classmethod + def update_cfg_with_data_cfg(cls, cfg, data_cfg): + cfg["task"].vocoder = data_cfg.vocoder.get("type", "griffin_lim") + + @classmethod + def get_model_input( + cls, task, text: str, speaker: Optional[int] = None, verbose: bool = False + ): + phonemized = cls.phonemize( + text, + task.data_cfg.hub.get("lang", None), + task.data_cfg.hub.get("phonemizer", None), + task.data_cfg.hub.get("preserve_punct", False), + task.data_cfg.hub.get("to_simplified_zh", False), + ) + tkn_cfg = task.data_cfg.bpe_tokenizer + tokenized = cls.tokenize(phonemized, tkn_cfg) + if verbose: + logger.info(f"text: {text}") + logger.info(f"phonemized: {phonemized}") + logger.info(f"tokenized: {tokenized}") + + spk = task.data_cfg.hub.get("speaker", speaker) + n_speakers = len(task.speaker_to_id or {}) + if spk is None and n_speakers > 0: + spk = random.randint(0, n_speakers - 1) + if spk is not None: + spk = max(0, min(spk, n_speakers - 1)) + if verbose: + logger.info(f"speaker: {spk}") + spk = None if spk is None else torch.Tensor([[spk]]).long() + + src_tokens = task.src_dict.encode_line(tokenized, add_if_not_exist=False).view( + 1, -1 + ) + src_lengths = torch.Tensor([len(tokenized.split())]).long() + return { + "net_input": { + "src_tokens": src_tokens, + "src_lengths": src_lengths, + "prev_output_tokens": None, + }, + "target_lengths": None, + "speaker": spk, + } + + @classmethod + def get_prediction(cls, task, model, generator, sample) -> Tuple[torch.Tensor, int]: + prediction = generator.generate(model, sample) + return prediction[0]["waveform"], task.sr + + def predict( + self, text: str, speaker: Optional[int] = None, verbose: bool = False + ) -> Tuple[torch.Tensor, int]: + sample = self.get_model_input(self.task, text, speaker, verbose=verbose) + return self.get_prediction(self.task, self.model, self.generator, sample) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/tacotron2.py b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/tacotron2.py new file mode 100644 index 00000000..4df40756 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/tacotron2.py @@ -0,0 +1,380 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch +from torch import nn +from torch.nn import functional as F + +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + FairseqIncrementalDecoder, + register_model, + register_model_architecture, +) +from fairseq.modules import LSTMCellWithZoneOut, LocationAttention + + +logger = logging.getLogger(__name__) + + +def encoder_init(m): + if isinstance(m, nn.Conv1d): + nn.init.xavier_uniform_(m.weight, torch.nn.init.calculate_gain("relu")) + + +class Tacotron2Encoder(FairseqEncoder): + def __init__(self, args, src_dict, embed_speaker): + super().__init__(src_dict) + self.padding_idx = src_dict.pad() + self.embed_speaker = embed_speaker + self.spk_emb_proj = None + if embed_speaker is not None: + self.spk_emb_proj = nn.Linear( + args.encoder_embed_dim + args.speaker_embed_dim, args.encoder_embed_dim + ) + + self.embed_tokens = nn.Embedding( + len(src_dict), args.encoder_embed_dim, padding_idx=self.padding_idx + ) + + assert args.encoder_conv_kernel_size % 2 == 1 + self.convolutions = nn.ModuleList( + nn.Sequential( + nn.Conv1d( + args.encoder_embed_dim, + args.encoder_embed_dim, + kernel_size=args.encoder_conv_kernel_size, + padding=((args.encoder_conv_kernel_size - 1) // 2), + ), + nn.BatchNorm1d(args.encoder_embed_dim), + nn.ReLU(), + nn.Dropout(args.encoder_dropout), + ) + for _ in range(args.encoder_conv_layers) + ) + + self.lstm = nn.LSTM( + args.encoder_embed_dim, + args.encoder_embed_dim // 2, + num_layers=args.encoder_lstm_layers, + batch_first=True, + bidirectional=True, + ) + + self.apply(encoder_init) + + def forward(self, src_tokens, src_lengths=None, speaker=None, **kwargs): + x = self.embed_tokens(src_tokens) + x = x.transpose(1, 2).contiguous() # B x T x C -> B x C x T + for conv in self.convolutions: + x = conv(x) + x = x.transpose(1, 2).contiguous() # B x C x T -> B x T x C + + src_lengths = src_lengths.cpu().long() + x = nn.utils.rnn.pack_padded_sequence(x, src_lengths, batch_first=True) + x = self.lstm(x)[0] + x = nn.utils.rnn.pad_packed_sequence(x, batch_first=True)[0] + + encoder_padding_mask = src_tokens.eq(self.padding_idx) + + if self.embed_speaker is not None: + seq_len, bsz, _ = x.size() + emb = self.embed_speaker(speaker).expand(seq_len, bsz, -1) + x = self.spk_emb_proj(torch.cat([x, emb], dim=2)) + + return { + "encoder_out": [x], # B x T x C + "encoder_padding_mask": encoder_padding_mask, # B x T + } + + +class Prenet(nn.Module): + def __init__(self, in_dim, n_layers, n_units, dropout): + super().__init__() + self.layers = nn.ModuleList( + nn.Sequential(nn.Linear(in_dim if i == 0 else n_units, n_units), nn.ReLU()) + for i in range(n_layers) + ) + self.dropout = dropout + + def forward(self, x): + for layer in self.layers: + x = F.dropout(layer(x), p=self.dropout) # always applies dropout + return x + + +class Postnet(nn.Module): + def __init__(self, in_dim, n_channels, kernel_size, n_layers, dropout): + super(Postnet, self).__init__() + self.convolutions = nn.ModuleList() + assert kernel_size % 2 == 1 + for i in range(n_layers): + cur_layers = ( + [ + nn.Conv1d( + in_dim if i == 0 else n_channels, + n_channels if i < n_layers - 1 else in_dim, + kernel_size=kernel_size, + padding=((kernel_size - 1) // 2), + ), + nn.BatchNorm1d(n_channels if i < n_layers - 1 else in_dim), + ] + + ([nn.Tanh()] if i < n_layers - 1 else []) + + [nn.Dropout(dropout)] + ) + nn.init.xavier_uniform_( + cur_layers[0].weight, + torch.nn.init.calculate_gain("tanh" if i < n_layers - 1 else "linear"), + ) + self.convolutions.append(nn.Sequential(*cur_layers)) + + def forward(self, x): + x = x.transpose(1, 2) # B x T x C -> B x C x T + for conv in self.convolutions: + x = conv(x) + return x.transpose(1, 2) + + +def decoder_init(m): + if isinstance(m, torch.nn.Conv1d): + nn.init.xavier_uniform_(m.weight, torch.nn.init.calculate_gain("tanh")) + + +class Tacotron2Decoder(FairseqIncrementalDecoder): + def __init__(self, args, src_dict): + super().__init__(None) + self.args = args + self.n_frames_per_step = args.n_frames_per_step + self.out_dim = args.output_frame_dim * args.n_frames_per_step + + self.prenet = Prenet( + self.out_dim, args.prenet_layers, args.prenet_dim, args.prenet_dropout + ) + + # take prev_context, prev_frame, (speaker embedding) as input + self.attention_lstm = LSTMCellWithZoneOut( + args.zoneout, + args.prenet_dim + args.encoder_embed_dim, + args.decoder_lstm_dim, + ) + + # take attention_lstm output, attention_state, encoder_out as input + self.attention = LocationAttention( + args.attention_dim, + args.encoder_embed_dim, + args.decoder_lstm_dim, + (1 + int(args.attention_use_cumprob)), + args.attention_conv_dim, + args.attention_conv_kernel_size, + ) + + # take attention_lstm output, context, (gated_latent) as input + self.lstm = nn.ModuleList( + LSTMCellWithZoneOut( + args.zoneout, + args.encoder_embed_dim + args.decoder_lstm_dim, + args.decoder_lstm_dim, + ) + for i in range(args.decoder_lstm_layers) + ) + + proj_in_dim = args.encoder_embed_dim + args.decoder_lstm_dim + self.feat_proj = nn.Linear(proj_in_dim, self.out_dim) + self.eos_proj = nn.Linear(proj_in_dim, 1) + + self.postnet = Postnet( + self.out_dim, + args.postnet_conv_dim, + args.postnet_conv_kernel_size, + args.postnet_layers, + args.postnet_dropout, + ) + + self.ctc_proj = None + if getattr(args, "ctc_weight", 0.0) > 0.0: + self.ctc_proj = nn.Linear(self.out_dim, len(src_dict)) + + self.apply(decoder_init) + + def _get_states(self, incremental_state, enc_out): + bsz, in_len, _ = enc_out.size() + alstm_h = self.get_incremental_state(incremental_state, "alstm_h") + if alstm_h is None: + alstm_h = enc_out.new_zeros(bsz, self.args.decoder_lstm_dim) + alstm_c = self.get_incremental_state(incremental_state, "alstm_c") + if alstm_c is None: + alstm_c = enc_out.new_zeros(bsz, self.args.decoder_lstm_dim) + + lstm_h = self.get_incremental_state(incremental_state, "lstm_h") + if lstm_h is None: + lstm_h = [ + enc_out.new_zeros(bsz, self.args.decoder_lstm_dim) + for _ in range(self.args.decoder_lstm_layers) + ] + lstm_c = self.get_incremental_state(incremental_state, "lstm_c") + if lstm_c is None: + lstm_c = [ + enc_out.new_zeros(bsz, self.args.decoder_lstm_dim) + for _ in range(self.args.decoder_lstm_layers) + ] + + attn_w = self.get_incremental_state(incremental_state, "attn_w") + if attn_w is None: + attn_w = enc_out.new_zeros(bsz, in_len) + attn_w_cum = self.get_incremental_state(incremental_state, "attn_w_cum") + if attn_w_cum is None: + attn_w_cum = enc_out.new_zeros(bsz, in_len) + return alstm_h, alstm_c, lstm_h, lstm_c, attn_w, attn_w_cum + + def _get_init_attn_c(self, enc_out, enc_mask): + bsz = enc_out.size(0) + if self.args.init_attn_c == "zero": + return enc_out.new_zeros(bsz, self.args.encoder_embed_dim) + elif self.args.init_attn_c == "avg": + enc_w = (~enc_mask).type(enc_out.type()) + enc_w = enc_w / enc_w.sum(dim=1, keepdim=True) + return torch.sum(enc_out * enc_w.unsqueeze(2), dim=1) + else: + raise ValueError(f"{self.args.init_attn_c} not supported") + + def forward( + self, + prev_output_tokens, + encoder_out=None, + incremental_state=None, + target_lengths=None, + **kwargs, + ): + enc_mask = encoder_out["encoder_padding_mask"] + enc_out = encoder_out["encoder_out"][0] + in_len = enc_out.size(1) + + if incremental_state is not None: + prev_output_tokens = prev_output_tokens[:, -1:, :] + bsz, out_len, _ = prev_output_tokens.size() + + prenet_out = self.prenet(prev_output_tokens) + (alstm_h, alstm_c, lstm_h, lstm_c, attn_w, attn_w_cum) = self._get_states( + incremental_state, enc_out + ) + attn_ctx = self._get_init_attn_c(enc_out, enc_mask) + + attn_out = enc_out.new_zeros(bsz, in_len, out_len) + feat_out = enc_out.new_zeros(bsz, out_len, self.out_dim) + eos_out = enc_out.new_zeros(bsz, out_len) + for t in range(out_len): + alstm_in = torch.cat((attn_ctx, prenet_out[:, t, :]), dim=1) + alstm_h, alstm_c = self.attention_lstm(alstm_in, (alstm_h, alstm_c)) + + attn_state = attn_w.unsqueeze(1) + if self.args.attention_use_cumprob: + attn_state = torch.stack((attn_w, attn_w_cum), dim=1) + attn_ctx, attn_w = self.attention(enc_out, enc_mask, alstm_h, attn_state) + attn_w_cum = attn_w_cum + attn_w + attn_out[:, :, t] = attn_w + + for i, cur_lstm in enumerate(self.lstm): + if i == 0: + lstm_in = torch.cat((attn_ctx, alstm_h), dim=1) + else: + lstm_in = torch.cat((attn_ctx, lstm_h[i - 1]), dim=1) + lstm_h[i], lstm_c[i] = cur_lstm(lstm_in, (lstm_h[i], lstm_c[i])) + + proj_in = torch.cat((attn_ctx, lstm_h[-1]), dim=1) + feat_out[:, t, :] = self.feat_proj(proj_in) + eos_out[:, t] = self.eos_proj(proj_in).squeeze(1) + self.attention.clear_cache() + + self.set_incremental_state(incremental_state, "alstm_h", alstm_h) + self.set_incremental_state(incremental_state, "alstm_c", alstm_c) + self.set_incremental_state(incremental_state, "lstm_h", lstm_h) + self.set_incremental_state(incremental_state, "lstm_c", lstm_c) + self.set_incremental_state(incremental_state, "attn_w", attn_w) + self.set_incremental_state(incremental_state, "attn_w_cum", attn_w_cum) + + post_feat_out = feat_out + self.postnet(feat_out) + eos_out = eos_out.view(bsz, out_len, 1) + return post_feat_out, eos_out, {"attn": attn_out, "feature_out": feat_out} + + +@register_model("tacotron_2") +class Tacotron2Model(FairseqEncoderDecoderModel): + """ + Implementation for https://arxiv.org/pdf/1712.05884.pdf + """ + + @staticmethod + def add_args(parser): + # encoder + parser.add_argument("--encoder-dropout", type=float) + parser.add_argument("--encoder-embed-dim", type=int) + parser.add_argument("--encoder-conv-layers", type=int) + parser.add_argument("--encoder-conv-kernel-size", type=int) + parser.add_argument("--encoder-lstm-layers", type=int) + # decoder + parser.add_argument("--attention-dim", type=int) + parser.add_argument("--attention-conv-dim", type=int) + parser.add_argument("--attention-conv-kernel-size", type=int) + parser.add_argument("--prenet-dropout", type=float) + parser.add_argument("--prenet-layers", type=int) + parser.add_argument("--prenet-dim", type=int) + parser.add_argument("--postnet-dropout", type=float) + parser.add_argument("--postnet-layers", type=int) + parser.add_argument("--postnet-conv-dim", type=int) + parser.add_argument("--postnet-conv-kernel-size", type=int) + parser.add_argument("--init-attn-c", type=str) + parser.add_argument("--attention-use-cumprob", action="store_true") + parser.add_argument("--zoneout", type=float) + parser.add_argument("--decoder-lstm-layers", type=int) + parser.add_argument("--decoder-lstm-dim", type=int) + parser.add_argument("--output-frame-dim", type=int) + + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self._num_updates = 0 + + @classmethod + def build_model(cls, args, task): + embed_speaker = task.get_speaker_embeddings(args) + encoder = Tacotron2Encoder(args, task.src_dict, embed_speaker) + decoder = Tacotron2Decoder(args, task.src_dict) + return cls(encoder, decoder) + + def forward_encoder(self, src_tokens, src_lengths, **kwargs): + return self.encoder(src_tokens, src_lengths=src_lengths, **kwargs) + + def set_num_updates(self, num_updates): + super().set_num_updates(num_updates) + self._num_updates = num_updates + + +@register_model_architecture("tacotron_2", "tacotron_2") +def base_architecture(args): + # encoder + args.encoder_dropout = getattr(args, "encoder_dropout", 0.5) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_conv_layers = getattr(args, "encoder_conv_layers", 3) + args.encoder_conv_kernel_size = getattr(args, "encoder_conv_kernel_size", 5) + args.encoder_lstm_layers = getattr(args, "encoder_lstm_layers", 1) + # decoder + args.attention_dim = getattr(args, "attention_dim", 128) + args.attention_conv_dim = getattr(args, "attention_conv_dim", 32) + args.attention_conv_kernel_size = getattr(args, "attention_conv_kernel_size", 15) + args.prenet_dropout = getattr(args, "prenet_dropout", 0.5) + args.prenet_layers = getattr(args, "prenet_layers", 2) + args.prenet_dim = getattr(args, "prenet_dim", 256) + args.postnet_dropout = getattr(args, "postnet_dropout", 0.5) + args.postnet_layers = getattr(args, "postnet_layers", 5) + args.postnet_conv_dim = getattr(args, "postnet_conv_dim", 512) + args.postnet_conv_kernel_size = getattr(args, "postnet_conv_kernel_size", 5) + args.init_attn_c = getattr(args, "init_attn_c", "zero") + args.attention_use_cumprob = getattr(args, "attention_use_cumprob", True) + args.zoneout = getattr(args, "zoneout", 0.1) + args.decoder_lstm_layers = getattr(args, "decoder_lstm_layers", 2) + args.decoder_lstm_dim = getattr(args, "decoder_lstm_dim", 1024) + args.output_frame_dim = getattr(args, "output_frame_dim", 80) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/tts_transformer.py b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/tts_transformer.py new file mode 100644 index 00000000..19afc2b7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/tts_transformer.py @@ -0,0 +1,454 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from typing import List, Optional + +import torch +from torch import nn + +from fairseq import utils +from fairseq.data.data_utils import lengths_to_padding_mask +from fairseq.models import ( + FairseqEncoder, + FairseqEncoderDecoderModel, + FairseqIncrementalDecoder, + register_model, + register_model_architecture, +) +from fairseq.models.text_to_speech.hub_interface import TTSHubInterface +from fairseq.models.text_to_speech.tacotron2 import Postnet, Prenet +from fairseq.modules import ( + FairseqDropout, + LayerNorm, + PositionalEmbedding, + TransformerDecoderLayer, + TransformerEncoderLayer, +) + +logger = logging.getLogger(__name__) + + +def encoder_init(m): + if isinstance(m, nn.Conv1d): + nn.init.xavier_uniform_(m.weight, torch.nn.init.calculate_gain("relu")) + + +def Embedding(num_embeddings, embedding_dim): + m = nn.Embedding(num_embeddings, embedding_dim) + nn.init.normal_(m.weight, mean=0, std=embedding_dim**-0.5) + return m + + +class TTSTransformerEncoder(FairseqEncoder): + def __init__(self, args, src_dict, embed_speaker): + super().__init__(src_dict) + self.padding_idx = src_dict.pad() + self.embed_speaker = embed_speaker + self.spk_emb_proj = None + if embed_speaker is not None: + self.spk_emb_proj = nn.Linear( + args.encoder_embed_dim + args.speaker_embed_dim, args.encoder_embed_dim + ) + + self.dropout_module = FairseqDropout( + p=args.dropout, module_name=self.__class__.__name__ + ) + self.embed_tokens = nn.Embedding( + len(src_dict), args.encoder_embed_dim, padding_idx=self.padding_idx + ) + assert args.encoder_conv_kernel_size % 2 == 1 + self.prenet = nn.ModuleList( + nn.Sequential( + nn.Conv1d( + args.encoder_embed_dim, + args.encoder_embed_dim, + kernel_size=args.encoder_conv_kernel_size, + padding=((args.encoder_conv_kernel_size - 1) // 2), + ), + nn.BatchNorm1d(args.encoder_embed_dim), + nn.ReLU(), + nn.Dropout(args.encoder_dropout), + ) + for _ in range(args.encoder_conv_layers) + ) + self.prenet_proj = nn.Linear(args.encoder_embed_dim, args.encoder_embed_dim) + self.embed_positions = PositionalEmbedding( + args.max_source_positions, args.encoder_embed_dim, self.padding_idx + ) + self.pos_emb_alpha = nn.Parameter(torch.ones(1)) + + self.transformer_layers = nn.ModuleList( + TransformerEncoderLayer(args) + for _ in range(args.encoder_transformer_layers) + ) + if args.encoder_normalize_before: + self.layer_norm = LayerNorm(args.encoder_embed_dim) + else: + self.layer_norm = None + + self.apply(encoder_init) + + def forward(self, src_tokens, src_lengths=None, speaker=None, **kwargs): + x = self.embed_tokens(src_tokens) + x = x.transpose(1, 2).contiguous() # B x T x C -> B x C x T + for conv in self.prenet: + x = conv(x) + x = x.transpose(1, 2).contiguous() # B x C x T -> B x T x C + x = self.prenet_proj(x) + + padding_mask = src_tokens.eq(self.padding_idx) + positions = self.embed_positions(padding_mask) + x += self.pos_emb_alpha * positions + x = self.dropout_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + for layer in self.transformer_layers: + x = layer(x, padding_mask) + + if self.layer_norm is not None: + x = self.layer_norm(x) + + if self.embed_speaker is not None: + seq_len, bsz, _ = x.size() + emb = self.embed_speaker(speaker).transpose(0, 1) + emb = emb.expand(seq_len, bsz, -1) + x = self.spk_emb_proj(torch.cat([x, emb], dim=2)) + + return { + "encoder_out": [x], # T x B x C + "encoder_padding_mask": [padding_mask] + if padding_mask.any() + else [], # B x T + "encoder_embedding": [], # B x T x C + "encoder_states": [], # List[T x B x C] + "src_tokens": [], + "src_lengths": [], + } + + +def decoder_init(m): + if isinstance(m, torch.nn.Conv1d): + nn.init.xavier_uniform_(m.weight, torch.nn.init.calculate_gain("tanh")) + + +class TTSTransformerDecoder(FairseqIncrementalDecoder): + def __init__(self, args, src_dict, padding_idx=1): + super().__init__(None) + self._future_mask = torch.empty(0) + + self.args = args + self.padding_idx = src_dict.pad() if src_dict else padding_idx + self.n_frames_per_step = args.n_frames_per_step + self.out_dim = args.output_frame_dim * args.n_frames_per_step + + self.dropout_module = FairseqDropout( + args.dropout, module_name=self.__class__.__name__ + ) + self.embed_positions = PositionalEmbedding( + args.max_target_positions, args.decoder_embed_dim, self.padding_idx + ) + self.pos_emb_alpha = nn.Parameter(torch.ones(1)) + self.prenet = nn.Sequential( + Prenet( + self.out_dim, args.prenet_layers, args.prenet_dim, args.prenet_dropout + ), + nn.Linear(args.prenet_dim, args.decoder_embed_dim), + ) + + self.n_transformer_layers = args.decoder_transformer_layers + self.transformer_layers = nn.ModuleList( + TransformerDecoderLayer(args) for _ in range(self.n_transformer_layers) + ) + if args.decoder_normalize_before: + self.layer_norm = LayerNorm(args.decoder_embed_dim) + else: + self.layer_norm = None + + self.feat_proj = nn.Linear(args.decoder_embed_dim, self.out_dim) + self.eos_proj = nn.Linear(args.decoder_embed_dim, 1) + + self.postnet = Postnet( + self.out_dim, + args.postnet_conv_dim, + args.postnet_conv_kernel_size, + args.postnet_layers, + args.postnet_dropout, + ) + + self.ctc_proj = None + if getattr(args, "ctc_weight", 0.0) > 0.0: + self.ctc_proj = nn.Linear(self.out_dim, len(src_dict)) + + self.apply(decoder_init) + + def extract_features( + self, + prev_outputs, + encoder_out=None, + incremental_state=None, + target_lengths=None, + speaker=None, + **kwargs, + ): + alignment_layer = self.n_transformer_layers - 1 + self_attn_padding_mask = lengths_to_padding_mask(target_lengths) + positions = self.embed_positions( + self_attn_padding_mask, incremental_state=incremental_state + ) + + if incremental_state is not None: + prev_outputs = prev_outputs[:, -1:, :] + self_attn_padding_mask = self_attn_padding_mask[:, -1:] + if positions is not None: + positions = positions[:, -1:] + + x = self.prenet(prev_outputs) + x += self.pos_emb_alpha * positions + x = self.dropout_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + if not self_attn_padding_mask.any(): + self_attn_padding_mask = None + + attn: Optional[torch.Tensor] = None + inner_states: List[Optional[torch.Tensor]] = [x] + for idx, transformer_layer in enumerate(self.transformer_layers): + if incremental_state is None: + self_attn_mask = self.buffered_future_mask(x) + else: + self_attn_mask = None + + x, layer_attn, _ = transformer_layer( + x, + encoder_out["encoder_out"][0] + if (encoder_out is not None and len(encoder_out["encoder_out"]) > 0) + else None, + encoder_out["encoder_padding_mask"][0] + if ( + encoder_out is not None + and len(encoder_out["encoder_padding_mask"]) > 0 + ) + else None, + incremental_state, + self_attn_mask=self_attn_mask, + self_attn_padding_mask=self_attn_padding_mask, + need_attn=bool((idx == alignment_layer)), + need_head_weights=bool((idx == alignment_layer)), + ) + inner_states.append(x) + if layer_attn is not None and idx == alignment_layer: + attn = layer_attn.float().to(x) + + if attn is not None: + # average probabilities over heads, transpose to + # (B, src_len, tgt_len) + attn = attn.mean(dim=0).transpose(2, 1) + + if self.layer_norm is not None: + x = self.layer_norm(x) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + return x, {"attn": attn, "inner_states": inner_states} + + def forward( + self, + prev_output_tokens, + encoder_out=None, + incremental_state=None, + target_lengths=None, + speaker=None, + **kwargs, + ): + x, extra = self.extract_features( + prev_output_tokens, + encoder_out=encoder_out, + incremental_state=incremental_state, + target_lengths=target_lengths, + speaker=speaker, + **kwargs, + ) + attn = extra["attn"] + feat_out = self.feat_proj(x) + bsz, seq_len, _ = x.size() + eos_out = self.eos_proj(x) + post_feat_out = feat_out + self.postnet(feat_out) + return ( + post_feat_out, + eos_out, + { + "attn": attn, + "feature_out": feat_out, + "inner_states": extra["inner_states"], + }, + ) + + def get_normalized_probs(self, net_output, log_probs, sample): + logits = self.ctc_proj(net_output[2]["feature_out"]) + if log_probs: + return utils.log_softmax(logits.float(), dim=-1) + else: + return utils.softmax(logits.float(), dim=-1) + + def buffered_future_mask(self, tensor): + dim = tensor.size(0) + # self._future_mask.device != tensor.device is not working in TorchScript. This is a workaround. + if ( + self._future_mask.size(0) == 0 + or (not self._future_mask.device == tensor.device) + or self._future_mask.size(0) < dim + ): + self._future_mask = torch.triu( + utils.fill_with_neg_inf(torch.zeros([dim, dim])), 1 + ) + self._future_mask = self._future_mask.to(tensor) + return self._future_mask[:dim, :dim] + + +@register_model("tts_transformer") +class TTSTransformerModel(FairseqEncoderDecoderModel): + """ + Implementation for https://arxiv.org/pdf/1809.08895.pdf + """ + + @classmethod + def hub_models(cls): + base_url = "http://dl.fbaipublicfiles.com/fairseq/s2" + model_ids = [ + "tts_transformer-en-ljspeech", + "tts_transformer-en-200_speaker-cv4", + "tts_transformer-es-css10", + "tts_transformer-fr-cv7_css10", + "tts_transformer-ru-cv7_css10", + "tts_transformer-zh-cv7_css10", + "tts_transformer-ar-cv7_css10", + "tts_transformer-tr-cv7_css10", + "tts_transformer-vi-cv7", + ] + return {i: f"{base_url}/{i}.tar.gz" for i in model_ids} + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + config_yaml="config.yaml", + vocoder: str = "griffin_lim", + fp16: bool = False, + **kwargs, + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + config_yaml=config_yaml, + vocoder=vocoder, + fp16=fp16, + **kwargs, + ) + return TTSHubInterface(x["args"], x["task"], x["models"][0]) + + @staticmethod + def add_args(parser): + parser.add_argument("--dropout", type=float) + parser.add_argument("--output-frame-dim", type=int) + parser.add_argument("--speaker-embed-dim", type=int) + # encoder prenet + parser.add_argument("--encoder-dropout", type=float) + parser.add_argument("--encoder-conv-layers", type=int) + parser.add_argument("--encoder-conv-kernel-size", type=int) + # encoder transformer layers + parser.add_argument("--encoder-transformer-layers", type=int) + parser.add_argument("--encoder-embed-dim", type=int) + parser.add_argument("--encoder-ffn-embed-dim", type=int) + parser.add_argument("--encoder-normalize-before", action="store_true") + parser.add_argument("--encoder-attention-heads", type=int) + parser.add_argument("--attention-dropout", type=float) + parser.add_argument("--activation-dropout", "--relu-dropout", type=float) + parser.add_argument("--activation-fn", type=str, default="relu") + # decoder prenet + parser.add_argument("--prenet-dropout", type=float) + parser.add_argument("--prenet-layers", type=int) + parser.add_argument("--prenet-dim", type=int) + # decoder postnet + parser.add_argument("--postnet-dropout", type=float) + parser.add_argument("--postnet-layers", type=int) + parser.add_argument("--postnet-conv-dim", type=int) + parser.add_argument("--postnet-conv-kernel-size", type=int) + # decoder transformer layers + parser.add_argument("--decoder-transformer-layers", type=int) + parser.add_argument("--decoder-embed-dim", type=int) + parser.add_argument("--decoder-ffn-embed-dim", type=int) + parser.add_argument("--decoder-normalize-before", action="store_true") + parser.add_argument("--decoder-attention-heads", type=int) + + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + self._num_updates = 0 + + @classmethod + def build_model(cls, args, task): + embed_speaker = task.get_speaker_embeddings(args) + encoder = TTSTransformerEncoder(args, task.src_dict, embed_speaker) + decoder = TTSTransformerDecoder(args, task.src_dict) + return cls(encoder, decoder) + + def forward_encoder(self, src_tokens, src_lengths, speaker=None, **kwargs): + return self.encoder( + src_tokens, src_lengths=src_lengths, speaker=speaker, **kwargs + ) + + def set_num_updates(self, num_updates): + super().set_num_updates(num_updates) + self._num_updates = num_updates + + +@register_model_architecture("tts_transformer", "tts_transformer") +def base_architecture(args): + args.dropout = getattr(args, "dropout", 0.1) + args.output_frame_dim = getattr(args, "output_frame_dim", 80) + args.speaker_embed_dim = getattr(args, "speaker_embed_dim", 64) + # encoder prenet + args.encoder_dropout = getattr(args, "encoder_dropout", 0.5) + args.encoder_conv_layers = getattr(args, "encoder_conv_layers", 3) + args.encoder_conv_kernel_size = getattr(args, "encoder_conv_kernel_size", 5) + # encoder transformer layers + args.encoder_transformer_layers = getattr(args, "encoder_transformer_layers", 6) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr( + args, "encoder_ffn_embed_dim", 4 * args.encoder_embed_dim + ) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.activation_fn = getattr(args, "activation_fn", "relu") + # decoder prenet + args.prenet_dropout = getattr(args, "prenet_dropout", 0.5) + args.prenet_layers = getattr(args, "prenet_layers", 2) + args.prenet_dim = getattr(args, "prenet_dim", 256) + # decoder postnet + args.postnet_dropout = getattr(args, "postnet_dropout", 0.5) + args.postnet_layers = getattr(args, "postnet_layers", 5) + args.postnet_conv_dim = getattr(args, "postnet_conv_dim", 512) + args.postnet_conv_kernel_size = getattr(args, "postnet_conv_kernel_size", 5) + # decoder transformer layers + args.decoder_transformer_layers = getattr(args, "decoder_transformer_layers", 6) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", 4 * args.decoder_embed_dim + ) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 4) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/vocoder.py b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/vocoder.py new file mode 100644 index 00000000..c3d71345 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/text_to_speech/vocoder.py @@ -0,0 +1,259 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import json +from typing import Dict + +import numpy as np +import torch +from torch import nn +import torch.nn.functional as F + +from fairseq.data.audio.audio_utils import ( + get_window, + get_fourier_basis, + get_mel_filters, + TTSSpectrogram, +) +from fairseq.data.audio.speech_to_text_dataset import S2TDataConfig +from fairseq.models.text_to_speech.codehifigan import CodeGenerator as CodeHiFiGANModel +from fairseq.models.text_to_speech.hifigan import Generator as HiFiGANModel + +logger = logging.getLogger(__name__) + + +class PseudoInverseMelScale(torch.nn.Module): + def __init__(self, n_stft, n_mels, sample_rate, f_min, f_max) -> None: + super(PseudoInverseMelScale, self).__init__() + self.n_mels = n_mels + basis = get_mel_filters(sample_rate, (n_stft - 1) * 2, n_mels, f_min, f_max) + basis = torch.pinverse(basis) # F x F_mel + self.register_buffer("basis", basis) + + def forward(self, melspec: torch.Tensor) -> torch.Tensor: + # pack batch + shape = melspec.shape # B_1 x ... x B_K x F_mel x T + n_mels, time = shape[-2], shape[-1] + melspec = melspec.view(-1, n_mels, time) + + freq, _ = self.basis.size() # F x F_mel + assert self.n_mels == n_mels, (self.n_mels, n_mels) + specgram = self.basis.matmul(melspec).clamp(min=0) + + # unpack batch + specgram = specgram.view(shape[:-2] + (freq, time)) + return specgram + + +class GriffinLim(torch.nn.Module): + def __init__( + self, + n_fft: int, + win_length: int, + hop_length: int, + n_iter: int, + window_fn=torch.hann_window, + ): + super(GriffinLim, self).__init__() + self.transform = TTSSpectrogram( + n_fft, win_length, hop_length, return_phase=True + ) + + basis = get_fourier_basis(n_fft) + basis = torch.pinverse(n_fft / hop_length * basis).T[:, None, :] + basis *= get_window(window_fn, n_fft, win_length) + self.register_buffer("basis", basis) + + self.n_fft = n_fft + self.win_length = win_length + self.hop_length = hop_length + self.n_iter = n_iter + + self.tiny = 1.1754944e-38 + + @classmethod + def get_window_sum_square( + cls, n_frames, hop_length, win_length, n_fft, window_fn=torch.hann_window + ) -> torch.Tensor: + w_sq = get_window(window_fn, n_fft, win_length) ** 2 + n = n_fft + hop_length * (n_frames - 1) + x = torch.zeros(n, dtype=torch.float32) + for i in range(n_frames): + ofst = i * hop_length + x[ofst : min(n, ofst + n_fft)] += w_sq[: max(0, min(n_fft, n - ofst))] + return x + + def inverse(self, magnitude: torch.Tensor, phase) -> torch.Tensor: + x = torch.cat( + [magnitude * torch.cos(phase), magnitude * torch.sin(phase)], dim=1 + ) + x = F.conv_transpose1d(x, self.basis, stride=self.hop_length) + win_sum_sq = self.get_window_sum_square( + magnitude.shape[-1], + hop_length=self.hop_length, + win_length=self.win_length, + n_fft=self.n_fft, + ).to(magnitude.device) + # remove modulation effects + approx_nonzero_indices = win_sum_sq > self.tiny + x[:, :, approx_nonzero_indices] /= win_sum_sq[approx_nonzero_indices] + x *= self.n_fft / self.hop_length + x = x[:, :, self.n_fft // 2 :] + x = x[:, :, : -self.n_fft // 2 :] + return x + + def forward(self, specgram: torch.Tensor) -> torch.Tensor: + angles = np.angle(np.exp(2j * np.pi * np.random.rand(*specgram.shape))) + angles = torch.from_numpy(angles).to(specgram) + _specgram = specgram.view(-1, specgram.shape[-2], specgram.shape[-1]) + waveform = self.inverse(_specgram, angles).squeeze(1) + for _ in range(self.n_iter): + _, angles = self.transform(waveform) + waveform = self.inverse(_specgram, angles).squeeze(1) + return waveform.squeeze(0) + + +class GriffinLimVocoder(nn.Module): + def __init__( + self, + sample_rate, + win_size, + hop_size, + n_fft, + n_mels, + f_min, + f_max, + window_fn, + spec_bwd_max_iter=32, + fp16=False, + ): + super().__init__() + self.inv_mel_transform = PseudoInverseMelScale( + n_stft=n_fft // 2 + 1, + n_mels=n_mels, + sample_rate=sample_rate, + f_min=f_min, + f_max=f_max, + ) + self.gl_transform = GriffinLim( + n_fft=n_fft, + win_length=win_size, + hop_length=hop_size, + window_fn=window_fn, + n_iter=spec_bwd_max_iter, + ) + if fp16: + self.half() + self.inv_mel_transform.half() + self.gl_transform.half() + else: + self.float() + self.inv_mel_transform.float() + self.gl_transform.float() + + def forward(self, x): + # x: (B x) T x D -> (B x) 1 x T + # NOTE: batched forward produces noisier waveform. recommend running + # one utterance at a time + self.eval() + x = x.exp().transpose(-1, -2) + x = self.inv_mel_transform(x) + x = self.gl_transform(x) + return x + + @classmethod + def from_data_cfg(cls, args, data_cfg: S2TDataConfig): + feat_cfg = data_cfg.config["features"] + window_fn = getattr(torch, feat_cfg["window_fn"] + "_window") + return cls( + sample_rate=feat_cfg["sample_rate"], + win_size=int(feat_cfg["win_len_t"] * feat_cfg["sample_rate"]), + hop_size=int(feat_cfg["hop_len_t"] * feat_cfg["sample_rate"]), + n_fft=feat_cfg["n_fft"], + n_mels=feat_cfg["n_mels"], + f_min=feat_cfg["f_min"], + f_max=feat_cfg["f_max"], + window_fn=window_fn, + spec_bwd_max_iter=args.spec_bwd_max_iter, + fp16=args.fp16, + ) + + +class HiFiGANVocoder(nn.Module): + def __init__( + self, checkpoint_path: str, model_cfg: Dict[str, str], fp16: bool = False + ) -> None: + super().__init__() + self.model = HiFiGANModel(model_cfg) + state_dict = torch.load(checkpoint_path) + self.model.load_state_dict(state_dict["generator"]) + if fp16: + self.model.half() + logger.info(f"loaded HiFiGAN checkpoint from {checkpoint_path}") + + def forward(self, x: torch.Tensor) -> torch.Tensor: + # (B x) T x D -> (B x) 1 x T + model = self.model.eval() + if len(x.shape) == 2: + return model(x.unsqueeze(0).transpose(1, 2)).detach().squeeze(0) + else: + return model(x.transpose(-1, -2)).detach() + + @classmethod + def from_data_cfg(cls, args, data_cfg: S2TDataConfig): + vocoder_cfg = data_cfg.vocoder + assert vocoder_cfg.get("type", "griffin_lim") == "hifigan" + with open(vocoder_cfg["config"]) as f: + model_cfg = json.load(f) + return cls(vocoder_cfg["checkpoint"], model_cfg, fp16=args.fp16) + + +class CodeHiFiGANVocoder(nn.Module): + def __init__( + self, checkpoint_path: str, model_cfg: Dict[str, str], fp16: bool = False + ) -> None: + super().__init__() + self.model = CodeHiFiGANModel(model_cfg) + state_dict = torch.load(checkpoint_path) + self.model.load_state_dict(state_dict["generator"]) + self.model.eval() + if fp16: + self.model.half() + self.model.remove_weight_norm() + logger.info(f"loaded CodeHiFiGAN checkpoint from {checkpoint_path}") + + def forward(self, x: Dict[str, torch.Tensor], dur_prediction=False) -> torch.Tensor: + assert "code" in x + x["dur_prediction"] = dur_prediction + + # remove invalid code + mask = x["code"] >= 0 + x["code"] = x["code"][mask].unsqueeze(dim=0) + if "f0" in x: + f0_up_ratio = x["f0"].size(1) // x["code"].size(1) + mask = mask.unsqueeze(2).repeat(1, 1, f0_up_ratio).view(-1, x["f0"].size(1)) + x["f0"] = x["f0"][mask].unsqueeze(dim=0) + + return self.model(**x).detach().squeeze() + + @classmethod + def from_data_cfg(cls, args, data_cfg): + vocoder_cfg = data_cfg.vocoder + assert vocoder_cfg is not None, "vocoder not specified in the data config" + with open(vocoder_cfg["config"]) as f: + model_cfg = json.load(f) + return cls(vocoder_cfg["checkpoint"], model_cfg, fp16=args.fp16) + + +def get_vocoder(args, data_cfg: S2TDataConfig): + if args.vocoder == "griffin_lim": + return GriffinLimVocoder.from_data_cfg(args, data_cfg) + elif args.vocoder == "hifigan": + return HiFiGANVocoder.from_data_cfg(args, data_cfg) + elif args.vocoder == "code_hifigan": + return CodeHiFiGANVocoder.from_data_cfg(args, data_cfg) + else: + raise ValueError("Unknown vocoder") diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/__init__.py new file mode 100644 index 00000000..681fca3d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/__init__.py @@ -0,0 +1,50 @@ +# Copyright (c) Facebook Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +from .transformer_config import ( + TransformerConfig, + DEFAULT_MAX_SOURCE_POSITIONS, + DEFAULT_MAX_TARGET_POSITIONS, + DEFAULT_MIN_PARAMS_TO_WRAP, +) +from .transformer_decoder import TransformerDecoder, TransformerDecoderBase, Linear +from .transformer_encoder import TransformerEncoder, TransformerEncoderBase +from .transformer_legacy import ( + TransformerModel, + base_architecture, + tiny_architecture, + transformer_iwslt_de_en, + transformer_wmt_en_de, + transformer_vaswani_wmt_en_de_big, + transformer_vaswani_wmt_en_fr_big, + transformer_wmt_en_de_big, + transformer_wmt_en_de_big_t2t, +) +from .transformer_base import TransformerModelBase, Embedding + + +__all__ = [ + "TransformerModelBase", + "TransformerConfig", + "TransformerDecoder", + "TransformerDecoderBase", + "TransformerEncoder", + "TransformerEncoderBase", + "TransformerModel", + "Embedding", + "Linear", + "base_architecture", + "tiny_architecture", + "transformer_iwslt_de_en", + "transformer_wmt_en_de", + "transformer_vaswani_wmt_en_de_big", + "transformer_vaswani_wmt_en_fr_big", + "transformer_wmt_en_de_big", + "transformer_wmt_en_de_big_t2t", + "DEFAULT_MAX_SOURCE_POSITIONS", + "DEFAULT_MAX_TARGET_POSITIONS", + "DEFAULT_MIN_PARAMS_TO_WRAP", +] diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_base.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_base.py new file mode 100644 index 00000000..5e025c90 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_base.py @@ -0,0 +1,176 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Dict, List, Optional, Tuple + +import torch +import torch.nn as nn +from torch import Tensor + +from fairseq import utils +from fairseq.dataclass.utils import gen_parser_from_dataclass +from fairseq.distributed import fsdp_wrap +from fairseq.models import FairseqEncoderDecoderModel +from fairseq.models.transformer import ( + TransformerConfig, + TransformerDecoderBase, + TransformerEncoderBase, +) + + +class TransformerModelBase(FairseqEncoderDecoderModel): + """ + Transformer model from `"Attention Is All You Need" (Vaswani, et al, 2017) + `_. + + Args: + encoder (TransformerEncoder): the encoder + decoder (TransformerDecoder): the decoder + + The Transformer model provides the following named architectures and + command-line arguments: + + .. argparse:: + :ref: fairseq.models.transformer_parser + :prog: + """ + + def __init__(self, cfg, encoder, decoder): + super().__init__(encoder, decoder) + self.cfg = cfg + self.supports_align_args = True + + @classmethod + def add_args(cls, parser): + """Add model-specific arguments to the parser.""" + # we want to build the args recursively in this case. + gen_parser_from_dataclass( + parser, TransformerConfig(), delete_default=False, with_prefix="" + ) + + @classmethod + def build_model(cls, cfg, task): + """Build a new model instance.""" + + # -- TODO T96535332 + # bug caused by interaction between OmegaConf II and argparsing + cfg.decoder.input_dim = int(cfg.decoder.input_dim) + cfg.decoder.output_dim = int(cfg.decoder.output_dim) + # -- + + if cfg.encoder.layers_to_keep: + cfg.encoder.layers = len(cfg.encoder.layers_to_keep.split(",")) + if cfg.decoder.layers_to_keep: + cfg.decoder.layers = len(cfg.decoder.layers_to_keep.split(",")) + + src_dict, tgt_dict = task.source_dictionary, task.target_dictionary + + if cfg.share_all_embeddings: + if src_dict != tgt_dict: + raise ValueError("--share-all-embeddings requires a joined dictionary") + if cfg.encoder.embed_dim != cfg.decoder.embed_dim: + raise ValueError( + "--share-all-embeddings requires --encoder-embed-dim to match --decoder-embed-dim" + ) + if cfg.decoder.embed_path and ( + cfg.decoder.embed_path != cfg.encoder.embed_path + ): + raise ValueError( + "--share-all-embeddings not compatible with --decoder-embed-path" + ) + encoder_embed_tokens = cls.build_embedding( + cfg, src_dict, cfg.encoder.embed_dim, cfg.encoder.embed_path + ) + decoder_embed_tokens = encoder_embed_tokens + cfg.share_decoder_input_output_embed = True + else: + encoder_embed_tokens = cls.build_embedding( + cfg, src_dict, cfg.encoder.embed_dim, cfg.encoder.embed_path + ) + decoder_embed_tokens = cls.build_embedding( + cfg, tgt_dict, cfg.decoder.embed_dim, cfg.decoder.embed_path + ) + if cfg.offload_activations: + cfg.checkpoint_activations = True # offloading implies checkpointing + encoder = cls.build_encoder(cfg, src_dict, encoder_embed_tokens) + decoder = cls.build_decoder(cfg, tgt_dict, decoder_embed_tokens) + return cls(cfg, encoder, decoder) + + @classmethod + def build_embedding(cls, cfg, dictionary, embed_dim, path=None): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + + emb = Embedding(num_embeddings, embed_dim, padding_idx) + # if provided, load from preloaded dictionaries + if path: + embed_dict = utils.parse_embedding(path) + utils.load_embedding(embed_dict, dictionary, emb) + return emb + + @classmethod + def build_encoder(cls, cfg, src_dict, embed_tokens): + return TransformerEncoderBase(cfg, src_dict, embed_tokens) + + @classmethod + def build_decoder(cls, cfg, tgt_dict, embed_tokens): + return TransformerDecoderBase( + cfg, + tgt_dict, + embed_tokens, + no_encoder_attn=cfg.no_cross_attention, + ) + + # TorchScript doesn't support optional arguments with variable length (**kwargs). + # Current workaround is to add union of all arguments in child classes. + def forward( + self, + src_tokens, + src_lengths, + prev_output_tokens, + return_all_hiddens: bool = True, + features_only: bool = False, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + ): + """ + Run the forward pass for an encoder-decoder model. + + Copied from the base class, but without ``**kwargs``, + which are not supported by TorchScript. + """ + encoder_out = self.encoder( + src_tokens, src_lengths=src_lengths, return_all_hiddens=return_all_hiddens + ) + decoder_out = self.decoder( + prev_output_tokens, + encoder_out=encoder_out, + features_only=features_only, + alignment_layer=alignment_layer, + alignment_heads=alignment_heads, + src_lengths=src_lengths, + return_all_hiddens=return_all_hiddens, + ) + return decoder_out + + # Since get_normalized_probs is in the Fairseq Model which is not scriptable, + # I rewrite the get_normalized_probs from Base Class to call the + # helper function in the Base Class. + @torch.jit.export + def get_normalized_probs( + self, + net_output: Tuple[Tensor, Optional[Dict[str, List[Optional[Tensor]]]]], + log_probs: bool, + sample: Optional[Dict[str, Tensor]] = None, + ): + """Get normalized probabilities (or log probs) from a net's output.""" + return self.get_normalized_probs_scriptable(net_output, log_probs, sample) + + +def Embedding(num_embeddings, embedding_dim, padding_idx): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + nn.init.normal_(m.weight, mean=0, std=embedding_dim**-0.5) + nn.init.constant_(m.weight[padding_idx], 0) + return m diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_config.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_config.py new file mode 100644 index 00000000..119b030b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_config.py @@ -0,0 +1,333 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +import re +from dataclasses import dataclass, field, fields +from typing import List, Optional + +from omegaconf import II + +from fairseq import utils +from fairseq.dataclass import ChoiceEnum, FairseqDataclass +from fairseq.utils import safe_getattr, safe_hasattr + +DEFAULT_MAX_SOURCE_POSITIONS = 1024 +DEFAULT_MAX_TARGET_POSITIONS = 1024 + +DEFAULT_MIN_PARAMS_TO_WRAP = int(1e8) + +_NAME_PARSER = r"(decoder|encoder|quant_noise)_(.*)" + + +@dataclass +class EncDecBaseConfig(FairseqDataclass): + embed_path: Optional[str] = field( + default=None, metadata={"help": "path to pre-trained embedding"} + ) + embed_dim: Optional[int] = field( + default=512, metadata={"help": "embedding dimension"} + ) + ffn_embed_dim: int = field( + default=2048, metadata={"help": "embedding dimension for FFN"} + ) + layers: int = field(default=6, metadata={"help": "number of layers"}) + attention_heads: int = field( + default=8, metadata={"help": "number of attention heads"} + ) + normalize_before: bool = field( + default=False, metadata={"help": "apply layernorm before each block"} + ) + learned_pos: bool = field( + default=False, metadata={"help": "use learned positional embeddings"} + ) + # args for "Reducing Transformer Depth on Demand with Structured Dropout" (Fan et al., 2019) + layerdrop: float = field(default=0, metadata={"help": "LayerDrop probability"}) + layers_to_keep: Optional[List[int]] = field( + default=None, metadata={"help": "which layers to *keep* when pruning"} + ) + + xformers_att_config: Optional[str] = field( + default=None, + metadata={ + "help": "config for xFormers attention, defined in xformers.components.attention.AttentionConfig" + }, + ) + + +@dataclass +class DecoderConfig(EncDecBaseConfig): + input_dim: int = II("model.decoder.embed_dim") + output_dim: int = field( + default=II("model.decoder.embed_dim"), + metadata={ + "help": "decoder output dimension (extra linear layer if different from decoder embed dim)" + }, + ) + + def __post_init__(self): + # II doesn't work if we are just creating the object outside of hydra so fix that + if self.input_dim == II("model.decoder.embed_dim"): + self.input_dim = self.embed_dim + if self.output_dim == II("model.decoder.embed_dim"): + self.output_dim = self.embed_dim + + +@dataclass +class QuantNoiseConfig(FairseqDataclass): + pq: float = field( + default=0.0, + metadata={"help": "iterative PQ quantization noise at training time"}, + ) + pq_block_size: int = field( + default=8, + metadata={"help": "block size of quantization noise at training time"}, + ) + scalar: float = field( + default=0.0, + metadata={ + "help": "scalar quantization noise and scalar quantization at training time" + }, + ) + + +@dataclass +class TransformerConfig(FairseqDataclass): + activation_fn: ChoiceEnum(utils.get_available_activation_fns()) = field( + default="relu", + metadata={"help": "activation function to use"}, + ) + dropout: float = field(default=0.1, metadata={"help": "dropout probability"}) + attention_dropout: float = field( + default=0.0, metadata={"help": "dropout probability for attention weights"} + ) + activation_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability after activation in FFN.", + "alias": "--relu-dropout", + }, + ) + adaptive_input: bool = False + encoder: EncDecBaseConfig = EncDecBaseConfig() + # TODO should really be in the encoder config + max_source_positions: int = field( + default=DEFAULT_MAX_SOURCE_POSITIONS, + metadata={"help": "Maximum input length supported by the encoder"}, + ) + decoder: DecoderConfig = DecoderConfig() + # TODO should really be in the decoder config + max_target_positions: int = field( + default=DEFAULT_MAX_TARGET_POSITIONS, + metadata={"help": "Maximum output length supported by the decoder"}, + ) + share_decoder_input_output_embed: bool = field( + default=False, metadata={"help": "share decoder input and output embeddings"} + ) + share_all_embeddings: bool = field( + default=False, + metadata={ + "help": "share encoder, decoder and output embeddings (requires shared dictionary and embed dim)" + }, + ) + no_token_positional_embeddings: bool = field( + default=False, + metadata={ + "help": "if True, disables positional embeddings (outside self attention)" + }, + ) + adaptive_softmax_cutoff: Optional[List[int]] = field( + default=None, + metadata={ + "help": "list of adaptive softmax cutoff points. Must be used with adaptive_loss criterion" + }, + ) + adaptive_softmax_dropout: float = field( + default=0.0, + metadata={"help": "sets adaptive softmax dropout for the tail projections"}, + ) + adaptive_softmax_factor: float = field( + default=4, metadata={"help": "adaptive input factor"} + ) + layernorm_embedding: bool = field( + default=False, metadata={"help": "add layernorm to embedding"} + ) + tie_adaptive_weights: bool = field( + default=False, + metadata={ + "help": "if set, ties the weights of adaptive softmax and adaptive input" + }, + ) + tie_adaptive_proj: bool = field( + default=False, + metadata={ + "help": "if set, ties the projection weights of adaptive softmax and adaptive input" + }, + ) + no_scale_embedding: bool = field( + default=False, metadata={"help": "if True, dont scale embeddings"} + ) + checkpoint_activations: bool = field( + default=False, + metadata={ + "help": "checkpoint activations at each layer, which saves GPU memory usage at the cost of some additional compute" + }, + ) + offload_activations: bool = field( + default=False, + metadata={ + "help": "checkpoint activations at each layer, then save to gpu. Sets --checkpoint-activations." + }, + ) + # args for "Cross+Self-Attention for Transformer Models" (Peitz et al., 2019) + no_cross_attention: bool = field( + default=False, metadata={"help": "do not perform cross-attention"} + ) + cross_self_attention: bool = field( + default=False, metadata={"help": "perform cross+self-attention"} + ) + # args for Training with Quantization Noise for Extreme Model Compression ({Fan*, Stock*} et al., 2020) + quant_noise: QuantNoiseConfig = field(default=QuantNoiseConfig()) + min_params_to_wrap: int = field( + default=DEFAULT_MIN_PARAMS_TO_WRAP, + metadata={ + "help": "minimum number of params for a layer to be wrapped with FSDP() when " + "training with --ddp-backend=fully_sharded. Smaller values will " + "improve memory efficiency, but may make torch.distributed " + "communication less efficient due to smaller input sizes. This option " + "is set to 0 (i.e., always wrap) when --checkpoint-activations or " + "--offload-activations are passed." + }, + ) + # DEPRECATED field, but some old checkpoints might have it + char_inputs: bool = field( + default=False, metadata={"help": "if set, model takes character ids as input"} + ) + relu_dropout: float = 0.0 + # config for "BASE Layers: Simplifying Training of Large, Sparse Models" + base_layers: Optional[int] = field( + default=0, metadata={"help": "number of BASE layers in total"} + ) + base_sublayers: Optional[int] = field( + default=1, metadata={"help": "number of sublayers in each BASE layer"} + ) + base_shuffle: Optional[int] = field( + default=1, + metadata={"help": "shuffle tokens between workers before computing assignment"}, + ) + + export: bool = field( + default=False, + metadata={"help": "make the layernorm exportable with torchscript."}, + ) + + # copied from transformer_lm but expected in transformer_decoder: + no_decoder_final_norm: bool = field( + default=False, + metadata={"help": "don't add an extra layernorm after the last decoder block"}, + ) + + # We need to make this hierarchical dataclass like the flat namespace + # __getattr__ and __setattr__ here allow backward compatibility + # for subclasses of Transformer(Legacy) that depend on read/write on + # the flat namespace. + + def __getattr__(self, name): + match = re.match(_NAME_PARSER, name) + if match: + sub = safe_getattr(self, match[1]) + return safe_getattr(sub, match[2]) + raise AttributeError(f"invalid argument {name}.") + + def __setattr__(self, name, value): + match = re.match(_NAME_PARSER, name) + if match: + sub = safe_getattr(self, match[1]) + setattr(sub, match[2], value) + else: + super().__setattr__(name, value) + + @staticmethod + def _copy_keys(args, cls, prefix, seen): + """ + copy the prefixed keys (decoder_embed_dim) to the DC fields: decoder.embed_dim + """ + cfg = cls() + for fld in fields(cls): + # for all the fields in the DC, find the fields (e.g. embed_dim) + # in the namespace with the prefix (e.g. decoder) + # and set it on the dc. + args_key = f"{prefix}_{fld.name}" + if safe_hasattr(args, args_key): + seen.add(args_key) + setattr(cfg, fld.name, safe_getattr(args, args_key)) + if safe_hasattr(args, fld.name): + seen.add(fld.name) + setattr(cfg, fld.name, safe_getattr(args, fld.name)) + return cfg + + @classmethod + def from_namespace(cls, args): + if args is None: + return None + if not isinstance(args, cls): + seen = set() + config = cls() + # currently, we can go generically from DC fields to args hierarchically + # but we can't easily deconstruct a flat namespace to a hierarchical + # DC. Mostly because we could have a sub-dc called `decoder-foo` that should not + # go to the sub struct called `decoder`. There are ways to go around this, but let's keep it simple + # for now. + for fld in fields(cls): + # concretelly, the transformer_config know what sub-dc it has, so we go through all the dc fields + # and if it's one that has a sub-dc, we build that sub-dc with `copy_keys()` + if fld.name == "decoder": + if safe_hasattr(args, "decoder"): + # in some cases, the args we receive is already structured (as DictConfigs), so let's just build the correct DC + seen.add("decoder") + config.decoder = DecoderConfig(**args.decoder) + else: + config.decoder = cls._copy_keys( + args, DecoderConfig, "decoder", seen + ) + elif fld.name == "encoder": + # same but for encoder + if safe_hasattr(args, "encoder"): + seen.add("encoder") + config.encoder = EncDecBaseConfig(**args.encoder) + else: + config.encoder = cls._copy_keys( + args, EncDecBaseConfig, "encoder", seen + ) + elif fld.name == "quant_noise": + # same but for quant_noise + if safe_hasattr(args, "quant_noise"): + seen.add("quant_noise") + config.quant_noise = QuantNoiseConfig(**args.quant_noise) + else: + config.quant_noise = cls._copy_keys( + args, QuantNoiseConfig, "quant_noise", seen + ) + elif safe_hasattr(args, fld.name): + # if it's not a structure field, it's just a normal field, copy it over + seen.add(fld.name) + setattr(config, fld.name, safe_getattr(args, fld.name)) + # we got all the fields defined in the dataclass, but + # the argparse namespace might have extra args for two reasons: + # - we are in a legacy class so all the args are not declared in the dataclass. Ideally once everyone has defined a dataclass for their model, we won't need this + # - some places expect args to be there but never define them + args_dict = ( + args._asdict() + if safe_hasattr(args, "_asdict") + else vars(args) + if safe_hasattr(args, "__dict__") + else {} + ) # namedtupled doesn't have __dict__ :-/ + for key, value in args_dict.items(): + if key not in seen: + setattr(config, key, value) + return config + else: + return args diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_decoder.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_decoder.py new file mode 100644 index 00000000..61aaa098 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_decoder.py @@ -0,0 +1,480 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from typing import Any, Dict, List, Optional + +import torch +import torch.nn as nn +from torch import Tensor + +from fairseq import utils +from fairseq.distributed import fsdp_wrap +from fairseq.models import FairseqIncrementalDecoder +from fairseq.models.transformer import TransformerConfig +from fairseq.modules import ( + AdaptiveSoftmax, + BaseLayer, + FairseqDropout, + LayerDropModuleList, + LayerNorm, + PositionalEmbedding, + SinusoidalPositionalEmbedding, + transformer_layer, +) +from fairseq.modules.checkpoint_activations import checkpoint_wrapper +from fairseq.modules.quant_noise import quant_noise as apply_quant_noise_ + + +# rewrite name for backward compatibility in `make_generation_fast_` +def module_name_fordropout(module_name: str) -> str: + if module_name == "TransformerDecoderBase": + return "TransformerDecoder" + else: + return module_name + + +class TransformerDecoderBase(FairseqIncrementalDecoder): + """ + Transformer decoder consisting of *cfg.decoder.layers* layers. Each layer + is a :class:`TransformerDecoderLayer`. + + Args: + args (argparse.Namespace): parsed command-line arguments + dictionary (~fairseq.data.Dictionary): decoding dictionary + embed_tokens (torch.nn.Embedding): output embedding + no_encoder_attn (bool, optional): whether to attend to encoder outputs + (default: False). + """ + + def __init__( + self, + cfg, + dictionary, + embed_tokens, + no_encoder_attn=False, + output_projection=None, + ): + self.cfg = cfg + super().__init__(dictionary) + self.register_buffer("version", torch.Tensor([3])) + self._future_mask = torch.empty(0) + + self.dropout_module = FairseqDropout( + cfg.dropout, module_name=module_name_fordropout(self.__class__.__name__) + ) + self.decoder_layerdrop = cfg.decoder.layerdrop + self.share_input_output_embed = cfg.share_decoder_input_output_embed + + input_embed_dim = embed_tokens.embedding_dim + embed_dim = cfg.decoder.embed_dim + self.embed_dim = embed_dim + self.output_embed_dim = cfg.decoder.output_dim + + self.padding_idx = embed_tokens.padding_idx + self.max_target_positions = cfg.max_target_positions + + self.embed_tokens = embed_tokens + + self.embed_scale = 1.0 if cfg.no_scale_embedding else math.sqrt(embed_dim) + + if not cfg.adaptive_input and cfg.quant_noise.pq > 0: + self.quant_noise = apply_quant_noise_( + nn.Linear(embed_dim, embed_dim, bias=False), + cfg.quant_noise.pq, + cfg.quant_noise.pq_block_size, + ) + else: + self.quant_noise = None + + self.project_in_dim = ( + Linear(input_embed_dim, embed_dim, bias=False) + if embed_dim != input_embed_dim + else None + ) + self.embed_positions = ( + PositionalEmbedding( + self.max_target_positions, + embed_dim, + self.padding_idx, + learned=cfg.decoder.learned_pos, + ) + if not cfg.no_token_positional_embeddings + else None + ) + if cfg.layernorm_embedding: + self.layernorm_embedding = LayerNorm(embed_dim, export=cfg.export) + else: + self.layernorm_embedding = None + + self.cross_self_attention = cfg.cross_self_attention + + if self.decoder_layerdrop > 0.0: + self.layers = LayerDropModuleList(p=self.decoder_layerdrop) + else: + self.layers = nn.ModuleList([]) + self.layers.extend( + [ + self.build_decoder_layer(cfg, no_encoder_attn) + for _ in range(cfg.decoder.layers) + ] + ) + self.num_layers = len(self.layers) + + if cfg.decoder.normalize_before and not cfg.no_decoder_final_norm: + self.layer_norm = LayerNorm(embed_dim, export=cfg.export) + else: + self.layer_norm = None + + self.project_out_dim = ( + Linear(embed_dim, self.output_embed_dim, bias=False) + if embed_dim != self.output_embed_dim and not cfg.tie_adaptive_weights + else None + ) + + self.adaptive_softmax = None + self.output_projection = output_projection + if self.output_projection is None: + self.build_output_projection(cfg, dictionary, embed_tokens) + + def build_output_projection(self, cfg, dictionary, embed_tokens): + if cfg.adaptive_softmax_cutoff is not None: + self.adaptive_softmax = AdaptiveSoftmax( + len(dictionary), + self.output_embed_dim, + utils.eval_str_list(cfg.adaptive_softmax_cutoff, type=int), + dropout=cfg.adaptive_softmax_dropout, + adaptive_inputs=embed_tokens if cfg.tie_adaptive_weights else None, + factor=cfg.adaptive_softmax_factor, + tie_proj=cfg.tie_adaptive_proj, + ) + elif self.share_input_output_embed: + self.output_projection = nn.Linear( + self.embed_tokens.weight.shape[1], + self.embed_tokens.weight.shape[0], + bias=False, + ) + self.output_projection.weight = self.embed_tokens.weight + else: + self.output_projection = nn.Linear( + self.output_embed_dim, len(dictionary), bias=False + ) + nn.init.normal_( + self.output_projection.weight, mean=0, std=self.output_embed_dim**-0.5 + ) + num_base_layers = cfg.base_layers + for i in range(num_base_layers): + self.layers.insert( + ((i + 1) * cfg.decoder.layers) // (num_base_layers + 1), + BaseLayer(cfg), + ) + + def build_decoder_layer(self, cfg, no_encoder_attn=False): + layer = transformer_layer.TransformerDecoderLayerBase(cfg, no_encoder_attn) + checkpoint = cfg.checkpoint_activations + if checkpoint: + offload_to_cpu = cfg.offload_activations + layer = checkpoint_wrapper(layer, offload_to_cpu=offload_to_cpu) + # if we are checkpointing, enforce that FSDP always wraps the + # checkpointed layer, regardless of layer size + min_params_to_wrap = cfg.min_params_to_wrap if not checkpoint else 0 + layer = fsdp_wrap(layer, min_num_params=min_params_to_wrap) + return layer + + def forward( + self, + prev_output_tokens, + encoder_out: Optional[Dict[str, List[Tensor]]] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + features_only: bool = False, + full_context_alignment: bool = False, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + src_lengths: Optional[Any] = None, + return_all_hiddens: bool = False, + ): + """ + Args: + prev_output_tokens (LongTensor): previous decoder outputs of shape + `(batch, tgt_len)`, for teacher forcing + encoder_out (optional): output from the encoder, used for + encoder-side attention, should be of size T x B x C + incremental_state (dict): dictionary used for storing state during + :ref:`Incremental decoding` + features_only (bool, optional): only return features without + applying output layer (default: False). + full_context_alignment (bool, optional): don't apply + auto-regressive mask to self-attention (default: False). + + Returns: + tuple: + - the decoder's output of shape `(batch, tgt_len, vocab)` + - a dictionary with any model-specific outputs + """ + + x, extra = self.extract_features( + prev_output_tokens, + encoder_out=encoder_out, + incremental_state=incremental_state, + full_context_alignment=full_context_alignment, + alignment_layer=alignment_layer, + alignment_heads=alignment_heads, + ) + + if not features_only: + x = self.output_layer(x) + return x, extra + + def extract_features( + self, + prev_output_tokens, + encoder_out: Optional[Dict[str, List[Tensor]]], + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + full_context_alignment: bool = False, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + ): + return self.extract_features_scriptable( + prev_output_tokens, + encoder_out, + incremental_state, + full_context_alignment, + alignment_layer, + alignment_heads, + ) + + """ + A scriptable subclass of this class has an extract_features method and calls + super().extract_features, but super() is not supported in torchscript. A copy of + this function is made to be used in the subclass instead. + """ + + def extract_features_scriptable( + self, + prev_output_tokens, + encoder_out: Optional[Dict[str, List[Tensor]]], + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + full_context_alignment: bool = False, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + ): + """ + Similar to *forward* but only return features. + + Includes several features from "Jointly Learning to Align and + Translate with Transformer Models" (Garg et al., EMNLP 2019). + + Args: + full_context_alignment (bool, optional): don't apply + auto-regressive mask to self-attention (default: False). + alignment_layer (int, optional): return mean alignment over + heads at this layer (default: last layer). + alignment_heads (int, optional): only average alignment over + this many heads (default: all heads). + + Returns: + tuple: + - the decoder's features of shape `(batch, tgt_len, embed_dim)` + - a dictionary with any model-specific outputs + """ + bs, slen = prev_output_tokens.size() + if alignment_layer is None: + alignment_layer = self.num_layers - 1 + + enc: Optional[Tensor] = None + padding_mask: Optional[Tensor] = None + if encoder_out is not None and len(encoder_out["encoder_out"]) > 0: + enc = encoder_out["encoder_out"][0] + if encoder_out is not None and len(encoder_out["encoder_padding_mask"]) > 0: + padding_mask = encoder_out["encoder_padding_mask"][0] + + # embed positions + positions = None + if self.embed_positions is not None: + positions = self.embed_positions( + prev_output_tokens, incremental_state=incremental_state + ) + + if incremental_state is not None: + prev_output_tokens = prev_output_tokens[:, -1:] + if positions is not None: + positions = positions[:, -1:] + + # embed tokens and positions + x = self.embed_scale * self.embed_tokens(prev_output_tokens) + + if self.quant_noise is not None: + x = self.quant_noise(x) + + if self.project_in_dim is not None: + x = self.project_in_dim(x) + + if positions is not None: + x += positions + + if self.layernorm_embedding is not None: + x = self.layernorm_embedding(x) + + x = self.dropout_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + self_attn_padding_mask: Optional[Tensor] = None + if self.cross_self_attention or prev_output_tokens.eq(self.padding_idx).any(): + self_attn_padding_mask = prev_output_tokens.eq(self.padding_idx) + + # decoder layers + attn: Optional[Tensor] = None + inner_states: List[Optional[Tensor]] = [x] + for idx, layer in enumerate(self.layers): + if incremental_state is None and not full_context_alignment: + self_attn_mask = self.buffered_future_mask(x) + else: + self_attn_mask = None + + x, layer_attn, _ = layer( + x, + enc, + padding_mask, + incremental_state, + self_attn_mask=self_attn_mask, + self_attn_padding_mask=self_attn_padding_mask, + need_attn=bool((idx == alignment_layer)), + need_head_weights=bool((idx == alignment_layer)), + ) + inner_states.append(x) + if layer_attn is not None and idx == alignment_layer: + attn = layer_attn.float().to(x) + + if attn is not None: + if alignment_heads is not None: + attn = attn[:alignment_heads] + + # average probabilities over heads + attn = attn.mean(dim=0) + + if self.layer_norm is not None: + x = self.layer_norm(x) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + if self.project_out_dim is not None: + x = self.project_out_dim(x) + + return x, {"attn": [attn], "inner_states": inner_states} + + def output_layer(self, features): + """Project features to the vocabulary size.""" + if self.adaptive_softmax is None: + # project back to size of vocabulary + return self.output_projection(features) + else: + return features + + def max_positions(self): + """Maximum output length supported by the decoder.""" + if self.embed_positions is None: + return self.max_target_positions + return min(self.max_target_positions, self.embed_positions.max_positions) + + def buffered_future_mask(self, tensor): + dim = tensor.size(0) + # self._future_mask.device != tensor.device is not working in TorchScript. This is a workaround. + if ( + self._future_mask.size(0) == 0 + or (not self._future_mask.device == tensor.device) + or self._future_mask.size(0) < dim + ): + self._future_mask = torch.triu( + utils.fill_with_neg_inf(torch.zeros([dim, dim])), 1 + ) + self._future_mask = self._future_mask.to(tensor) + return self._future_mask[:dim, :dim] + + def upgrade_state_dict_named(self, state_dict, name): + """Upgrade a (possibly old) state dict for new versions of fairseq.""" + if isinstance(self.embed_positions, SinusoidalPositionalEmbedding): + weights_key = "{}.embed_positions.weights".format(name) + if weights_key in state_dict: + del state_dict[weights_key] + state_dict[ + "{}.embed_positions._float_tensor".format(name) + ] = torch.FloatTensor(1) + + if f"{name}.output_projection.weight" not in state_dict: + if self.share_input_output_embed: + embed_out_key = f"{name}.embed_tokens.weight" + else: + embed_out_key = f"{name}.embed_out" + if embed_out_key in state_dict: + state_dict[f"{name}.output_projection.weight"] = state_dict[ + embed_out_key + ] + if not self.share_input_output_embed: + del state_dict[embed_out_key] + + for i in range(self.num_layers): + # update layer norms + layer_norm_map = { + "0": "self_attn_layer_norm", + "1": "encoder_attn_layer_norm", + "2": "final_layer_norm", + } + for old, new in layer_norm_map.items(): + for m in ("weight", "bias"): + k = "{}.layers.{}.layer_norms.{}.{}".format(name, i, old, m) + if k in state_dict: + state_dict[ + "{}.layers.{}.{}.{}".format(name, i, new, m) + ] = state_dict[k] + del state_dict[k] + + version_key = "{}.version".format(name) + if utils.item(state_dict.get(version_key, torch.Tensor([1]))[0]) <= 2: + # earlier checkpoints did not normalize after the stack of layers + self.layer_norm = None + self.normalize = False + state_dict[version_key] = torch.Tensor([1]) + + return state_dict + + +def Linear(in_features, out_features, bias=True): + m = nn.Linear(in_features, out_features, bias) + nn.init.xavier_uniform_(m.weight) + if bias: + nn.init.constant_(m.bias, 0.0) + return m + + +class TransformerDecoder(TransformerDecoderBase): + def __init__( + self, + args, + dictionary, + embed_tokens, + no_encoder_attn=False, + output_projection=None, + ): + self.args = args + super().__init__( + TransformerConfig.from_namespace(args), + dictionary, + embed_tokens, + no_encoder_attn=no_encoder_attn, + output_projection=output_projection, + ) + + def build_output_projection(self, args, dictionary, embed_tokens): + super().build_output_projection( + TransformerConfig.from_namespace(args), dictionary, embed_tokens + ) + + def build_decoder_layer(self, args, no_encoder_attn=False): + return super().build_decoder_layer( + TransformerConfig.from_namespace(args), no_encoder_attn=no_encoder_attn + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_encoder.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_encoder.py new file mode 100644 index 00000000..0b7e6d83 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_encoder.py @@ -0,0 +1,365 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from typing import Dict, List, Optional + +import torch +import torch.nn as nn +from fairseq import utils +from fairseq.distributed import fsdp_wrap +from fairseq.models import FairseqEncoder +from fairseq.modules import ( + FairseqDropout, + LayerDropModuleList, + LayerNorm, + PositionalEmbedding, + SinusoidalPositionalEmbedding, +) +from fairseq.modules import transformer_layer +from fairseq.modules.checkpoint_activations import checkpoint_wrapper +from fairseq.modules.quant_noise import quant_noise as apply_quant_noise_ +from torch import Tensor +from fairseq.models.transformer import ( + TransformerConfig, +) + + +# rewrite name for backward compatibility in `make_generation_fast_` +def module_name_fordropout(module_name: str) -> str: + if module_name == "TransformerEncoderBase": + return "TransformerEncoder" + else: + return module_name + + +class TransformerEncoderBase(FairseqEncoder): + """ + Transformer encoder consisting of *cfg.encoder.layers* layers. Each layer + is a :class:`TransformerEncoderLayer`. + + Args: + args (argparse.Namespace): parsed command-line arguments + dictionary (~fairseq.data.Dictionary): encoding dictionary + embed_tokens (torch.nn.Embedding): input embedding + """ + + def __init__(self, cfg, dictionary, embed_tokens, return_fc=False): + self.cfg = cfg + super().__init__(dictionary) + self.register_buffer("version", torch.Tensor([3])) + + self.dropout_module = FairseqDropout( + cfg.dropout, module_name=module_name_fordropout(self.__class__.__name__) + ) + self.encoder_layerdrop = cfg.encoder.layerdrop + self.return_fc = return_fc + + embed_dim = embed_tokens.embedding_dim + self.padding_idx = embed_tokens.padding_idx + self.max_source_positions = cfg.max_source_positions + + self.embed_tokens = embed_tokens + + self.embed_scale = 1.0 if cfg.no_scale_embedding else math.sqrt(embed_dim) + + self.embed_positions = ( + PositionalEmbedding( + cfg.max_source_positions, + embed_dim, + self.padding_idx, + learned=cfg.encoder.learned_pos, + ) + if not cfg.no_token_positional_embeddings + else None + ) + if cfg.layernorm_embedding: + self.layernorm_embedding = LayerNorm(embed_dim, export=cfg.export) + else: + self.layernorm_embedding = None + + if not cfg.adaptive_input and cfg.quant_noise.pq > 0: + self.quant_noise = apply_quant_noise_( + nn.Linear(embed_dim, embed_dim, bias=False), + cfg.quant_noise.pq, + cfg.quant_noise.pq_block_size, + ) + else: + self.quant_noise = None + + if self.encoder_layerdrop > 0.0: + self.layers = LayerDropModuleList(p=self.encoder_layerdrop) + else: + self.layers = nn.ModuleList([]) + self.layers.extend( + [self.build_encoder_layer(cfg) for i in range(cfg.encoder.layers)] + ) + self.num_layers = len(self.layers) + + if cfg.encoder.normalize_before: + self.layer_norm = LayerNorm(embed_dim, export=cfg.export) + else: + self.layer_norm = None + + def build_encoder_layer(self, cfg): + layer = transformer_layer.TransformerEncoderLayerBase( + cfg, return_fc=self.return_fc + ) + checkpoint = cfg.checkpoint_activations + if checkpoint: + offload_to_cpu = cfg.offload_activations + layer = checkpoint_wrapper(layer, offload_to_cpu=offload_to_cpu) + # if we are checkpointing, enforce that FSDP always wraps the + # checkpointed layer, regardless of layer size + min_params_to_wrap = cfg.min_params_to_wrap if not checkpoint else 0 + layer = fsdp_wrap(layer, min_num_params=min_params_to_wrap) + return layer + + def forward_embedding( + self, src_tokens, token_embedding: Optional[torch.Tensor] = None + ): + # embed tokens and positions + if token_embedding is None: + token_embedding = self.embed_tokens(src_tokens) + x = embed = self.embed_scale * token_embedding + if self.embed_positions is not None: + x = embed + self.embed_positions(src_tokens) + if self.layernorm_embedding is not None: + x = self.layernorm_embedding(x) + x = self.dropout_module(x) + if self.quant_noise is not None: + x = self.quant_noise(x) + return x, embed + + def forward( + self, + src_tokens, + src_lengths: Optional[torch.Tensor] = None, + return_all_hiddens: bool = False, + token_embeddings: Optional[torch.Tensor] = None, + ): + """ + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (torch.LongTensor): lengths of each source sentence of + shape `(batch)` + return_all_hiddens (bool, optional): also return all of the + intermediate hidden states (default: False). + token_embeddings (torch.Tensor, optional): precomputed embeddings + default `None` will recompute embeddings + + Returns: + dict: + - **encoder_out** (Tensor): the last encoder layer's output of + shape `(src_len, batch, embed_dim)` + - **encoder_padding_mask** (ByteTensor): the positions of + padding elements of shape `(batch, src_len)` + - **encoder_embedding** (Tensor): the (scaled) embedding lookup + of shape `(batch, src_len, embed_dim)` + - **encoder_states** (List[Tensor]): all intermediate + hidden states of shape `(src_len, batch, embed_dim)`. + Only populated if *return_all_hiddens* is True. + """ + return self.forward_scriptable( + src_tokens, src_lengths, return_all_hiddens, token_embeddings + ) + + # TorchScript doesn't support super() method so that the scriptable Subclass + # can't access the base class model in Torchscript. + # Current workaround is to add a helper function with different name and + # call the helper function from scriptable Subclass. + def forward_scriptable( + self, + src_tokens, + src_lengths: Optional[torch.Tensor] = None, + return_all_hiddens: bool = False, + token_embeddings: Optional[torch.Tensor] = None, + ): + """ + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (torch.LongTensor): lengths of each source sentence of + shape `(batch)` + return_all_hiddens (bool, optional): also return all of the + intermediate hidden states (default: False). + token_embeddings (torch.Tensor, optional): precomputed embeddings + default `None` will recompute embeddings + + Returns: + dict: + - **encoder_out** (Tensor): the last encoder layer's output of + shape `(src_len, batch, embed_dim)` + - **encoder_padding_mask** (ByteTensor): the positions of + padding elements of shape `(batch, src_len)` + - **encoder_embedding** (Tensor): the (scaled) embedding lookup + of shape `(batch, src_len, embed_dim)` + - **encoder_states** (List[Tensor]): all intermediate + hidden states of shape `(src_len, batch, embed_dim)`. + Only populated if *return_all_hiddens* is True. + """ + # compute padding mask + encoder_padding_mask = src_tokens.eq(self.padding_idx) + has_pads = src_tokens.device.type == "xla" or encoder_padding_mask.any() + + x, encoder_embedding = self.forward_embedding(src_tokens, token_embeddings) + + # account for padding while computing the representation + if has_pads: + x = x * (1 - encoder_padding_mask.unsqueeze(-1).type_as(x)) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + encoder_states = [] + fc_results = [] + + if return_all_hiddens: + encoder_states.append(x) + + # encoder layers + for layer in self.layers: + lr = layer( + x, encoder_padding_mask=encoder_padding_mask if has_pads else None + ) + + if isinstance(lr, tuple) and len(lr) == 2: + x, fc_result = lr + else: + x = lr + fc_result = None + + if return_all_hiddens and not torch.jit.is_scripting(): + assert encoder_states is not None + encoder_states.append(x) + fc_results.append(fc_result) + + if self.layer_norm is not None: + x = self.layer_norm(x) + + # The Pytorch Mobile lite interpreter does not supports returning NamedTuple in + # `forward` so we use a dictionary instead. + # TorchScript does not support mixed values so the values are all lists. + # The empty list is equivalent to None. + src_lengths = ( + src_tokens.ne(self.padding_idx) + .sum(dim=1, dtype=torch.int32) + .reshape(-1, 1) + .contiguous() + ) + return { + "encoder_out": [x], # T x B x C + "encoder_padding_mask": [encoder_padding_mask], # B x T + "encoder_embedding": [encoder_embedding], # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "fc_results": fc_results, # List[T x B x C] + "src_tokens": [], + "src_lengths": [src_lengths], + } + + @torch.jit.export + def reorder_encoder_out(self, encoder_out: Dict[str, List[Tensor]], new_order): + """ + Reorder encoder output according to *new_order*. + + Args: + encoder_out: output from the ``forward()`` method + new_order (LongTensor): desired order + + Returns: + *encoder_out* rearranged according to *new_order* + """ + if len(encoder_out["encoder_out"]) == 0: + new_encoder_out = [] + else: + new_encoder_out = [encoder_out["encoder_out"][0].index_select(1, new_order)] + if len(encoder_out["encoder_padding_mask"]) == 0: + new_encoder_padding_mask = [] + else: + new_encoder_padding_mask = [ + encoder_out["encoder_padding_mask"][0].index_select(0, new_order) + ] + if len(encoder_out["encoder_embedding"]) == 0: + new_encoder_embedding = [] + else: + new_encoder_embedding = [ + encoder_out["encoder_embedding"][0].index_select(0, new_order) + ] + + if len(encoder_out["src_tokens"]) == 0: + src_tokens = [] + else: + src_tokens = [(encoder_out["src_tokens"][0]).index_select(0, new_order)] + + if len(encoder_out["src_lengths"]) == 0: + src_lengths = [] + else: + src_lengths = [(encoder_out["src_lengths"][0]).index_select(0, new_order)] + + encoder_states = encoder_out["encoder_states"] + if len(encoder_states) > 0: + for idx, state in enumerate(encoder_states): + encoder_states[idx] = state.index_select(1, new_order) + + return { + "encoder_out": new_encoder_out, # T x B x C + "encoder_padding_mask": new_encoder_padding_mask, # B x T + "encoder_embedding": new_encoder_embedding, # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": src_tokens, # B x T + "src_lengths": src_lengths, # B x 1 + } + + @torch.jit.export + def _reorder_encoder_out(self, encoder_out: Dict[str, List[Tensor]], new_order): + """Dummy re-order function for beamable enc-dec attention""" + return encoder_out + + def max_positions(self): + """Maximum input length supported by the encoder.""" + if self.embed_positions is None: + return self.max_source_positions + return min(self.max_source_positions, self.embed_positions.max_positions) + + def upgrade_state_dict_named(self, state_dict, name): + """Upgrade a (possibly old) state dict for new versions of fairseq.""" + if isinstance(self.embed_positions, SinusoidalPositionalEmbedding): + weights_key = "{}.embed_positions.weights".format(name) + if weights_key in state_dict: + print("deleting {0}".format(weights_key)) + del state_dict[weights_key] + state_dict[ + "{}.embed_positions._float_tensor".format(name) + ] = torch.FloatTensor(1) + for i in range(self.num_layers): + # update layer norms + self.layers[i].upgrade_state_dict_named( + state_dict, "{}.layers.{}".format(name, i) + ) + + version_key = "{}.version".format(name) + if utils.item(state_dict.get(version_key, torch.Tensor([1]))[0]) < 2: + # earlier checkpoints did not normalize after the stack of layers + self.layer_norm = None + self.normalize = False + state_dict[version_key] = torch.Tensor([1]) + return state_dict + + +class TransformerEncoder(TransformerEncoderBase): + def __init__(self, args, dictionary, embed_tokens, return_fc=False): + self.args = args + super().__init__( + TransformerConfig.from_namespace(args), + dictionary, + embed_tokens, + return_fc=return_fc, + ) + + def build_encoder_layer(self, args): + return super().build_encoder_layer( + TransformerConfig.from_namespace(args), + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_legacy.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_legacy.py new file mode 100644 index 00000000..af964674 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer/transformer_legacy.py @@ -0,0 +1,275 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.dataclass.utils import gen_parser_from_dataclass +from fairseq.models import ( + register_model, + register_model_architecture, +) +from fairseq.models.transformer.transformer_config import ( + TransformerConfig, + DEFAULT_MAX_SOURCE_POSITIONS, + DEFAULT_MAX_TARGET_POSITIONS, + DEFAULT_MIN_PARAMS_TO_WRAP, +) +from fairseq.models.transformer.transformer_base import ( + TransformerModelBase, +) + + +@register_model("transformer") +class TransformerModel(TransformerModelBase): + """ + This is the legacy implementation of the transformer model that + uses argparse for configuration. + """ + + @classmethod + def hub_models(cls): + # fmt: off + + def moses_subword(path): + return { + 'path': path, + 'tokenizer': 'moses', + 'bpe': 'subword_nmt', + } + + def moses_fastbpe(path): + return { + 'path': path, + 'tokenizer': 'moses', + 'bpe': 'fastbpe', + } + + def spm(path): + return { + 'path': path, + 'bpe': 'sentencepiece', + 'tokenizer': 'space', + } + + return { + 'transformer.wmt14.en-fr': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/wmt14.en-fr.joined-dict.transformer.tar.bz2'), + 'transformer.wmt16.en-de': 'https://dl.fbaipublicfiles.com/fairseq/models/wmt16.en-de.joined-dict.transformer.tar.bz2', + 'transformer.wmt18.en-de': moses_subword('https://dl.fbaipublicfiles.com/fairseq/models/wmt18.en-de.ensemble.tar.gz'), + 'transformer.wmt19.en-de': moses_fastbpe('https://dl.fbaipublicfiles.com/fairseq/models/wmt19.en-de.joined-dict.ensemble.tar.gz'), + 'transformer.wmt19.en-ru': moses_fastbpe('https://dl.fbaipublicfiles.com/fairseq/models/wmt19.en-ru.ensemble.tar.gz'), + 'transformer.wmt19.de-en': moses_fastbpe('https://dl.fbaipublicfiles.com/fairseq/models/wmt19.de-en.joined-dict.ensemble.tar.gz'), + 'transformer.wmt19.ru-en': moses_fastbpe('https://dl.fbaipublicfiles.com/fairseq/models/wmt19.ru-en.ensemble.tar.gz'), + 'transformer.wmt19.en-de.single_model': moses_fastbpe('https://dl.fbaipublicfiles.com/fairseq/models/wmt19.en-de.joined-dict.single_model.tar.gz'), + 'transformer.wmt19.en-ru.single_model': moses_fastbpe('https://dl.fbaipublicfiles.com/fairseq/models/wmt19.en-ru.single_model.tar.gz'), + 'transformer.wmt19.de-en.single_model': moses_fastbpe('https://dl.fbaipublicfiles.com/fairseq/models/wmt19.de-en.joined-dict.single_model.tar.gz'), + 'transformer.wmt19.ru-en.single_model': moses_fastbpe('https://dl.fbaipublicfiles.com/fairseq/models/wmt19.ru-en.single_model.tar.gz'), + 'transformer.wmt20.en-ta': spm('https://dl.fbaipublicfiles.com/fairseq/models/wmt20.en-ta.single.tar.gz'), + 'transformer.wmt20.en-iu.news': spm('https://dl.fbaipublicfiles.com/fairseq/models/wmt20.en-iu.news.single.tar.gz'), + 'transformer.wmt20.en-iu.nh': spm('https://dl.fbaipublicfiles.com/fairseq/models/wmt20.en-iu.nh.single.tar.gz'), + 'transformer.wmt20.ta-en': spm('https://dl.fbaipublicfiles.com/fairseq/models/wmt20.ta-en.single.tar.gz'), + 'transformer.wmt20.iu-en.news': spm('https://dl.fbaipublicfiles.com/fairseq/models/wmt20.iu-en.news.single.tar.gz'), + 'transformer.wmt20.iu-en.nh': spm('https://dl.fbaipublicfiles.com/fairseq/models/wmt20.iu-en.nh.single.tar.gz'), + 'transformer.flores101.mm100.615M': spm('https://dl.fbaipublicfiles.com/flores101/pretrained_models/flores101_mm100_615M.tar.gz'), + 'transformer.flores101.mm100.175M': spm('https://dl.fbaipublicfiles.com/flores101/pretrained_models/flores101_mm100_175M.tar.gz'), + } + # fmt: on + + def __init__(self, args, encoder, decoder): + cfg = TransformerConfig.from_namespace(args) + super().__init__(cfg, encoder, decoder) + self.args = args + + @classmethod + def add_args(cls, parser): + """Add model-specific arguments to the parser.""" + # we want to build the args recursively in this case. + # do not set defaults so that settings defaults from various architectures still works + gen_parser_from_dataclass( + parser, TransformerConfig(), delete_default=True, with_prefix="" + ) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + # make sure all arguments are present in older models + base_architecture(args) + + if args.encoder_layers_to_keep: + args.encoder_layers = len(args.encoder_layers_to_keep.split(",")) + if args.decoder_layers_to_keep: + args.decoder_layers = len(args.decoder_layers_to_keep.split(",")) + + if getattr(args, "max_source_positions", None) is None: + args.max_source_positions = DEFAULT_MAX_SOURCE_POSITIONS + if getattr(args, "max_target_positions", None) is None: + args.max_target_positions = DEFAULT_MAX_TARGET_POSITIONS + + src_dict, tgt_dict = task.source_dictionary, task.target_dictionary + + if args.share_all_embeddings: + if src_dict != tgt_dict: + raise ValueError("--share-all-embeddings requires a joined dictionary") + if args.encoder_embed_dim != args.decoder_embed_dim: + raise ValueError( + "--share-all-embeddings requires --encoder-embed-dim to match --decoder-embed-dim" + ) + if args.decoder_embed_path and ( + args.decoder_embed_path != args.encoder_embed_path + ): + raise ValueError( + "--share-all-embeddings not compatible with --decoder-embed-path" + ) + args.share_decoder_input_output_embed = True + + if getattr(args, "offload_activations", False): + args.checkpoint_activations = True # offloading implies checkpointing + + if not args.share_all_embeddings: + args.min_params_to_wrap = getattr( + args, "min_params_to_wrap", DEFAULT_MIN_PARAMS_TO_WRAP + ) + cfg = TransformerConfig.from_namespace(args) + return super().build_model(cfg, task) + + @classmethod + def build_embedding(cls, args, dictionary, embed_dim, path=None): + return super().build_embedding( + TransformerConfig.from_namespace(args), dictionary, embed_dim, path + ) + + @classmethod + def build_encoder(cls, args, src_dict, embed_tokens): + return super().build_encoder( + TransformerConfig.from_namespace(args), src_dict, embed_tokens + ) + + @classmethod + def build_decoder(cls, args, tgt_dict, embed_tokens): + return super().build_decoder( + TransformerConfig.from_namespace(args), tgt_dict, embed_tokens + ) + + +# architectures + + +@register_model_architecture("transformer", "transformer_tiny") +def tiny_architecture(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 64) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 64) + args.encoder_layers = getattr(args, "encoder_layers", 2) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 2) + args.decoder_layers = getattr(args, "decoder_layers", 2) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 2) + return base_architecture(args) + + +@register_model_architecture("transformer", "transformer") +def base_architecture(args): + args.encoder_embed_path = getattr(args, "encoder_embed_path", None) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 2048) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 8) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.encoder_learned_pos = getattr(args, "encoder_learned_pos", False) + args.decoder_embed_path = getattr(args, "decoder_embed_path", None) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", args.encoder_embed_dim) + args.decoder_ffn_embed_dim = getattr( + args, "decoder_ffn_embed_dim", args.encoder_ffn_embed_dim + ) + args.decoder_layers = getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 8) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", False) + args.decoder_learned_pos = getattr(args, "decoder_learned_pos", False) + args.attention_dropout = getattr(args, "attention_dropout", 0.0) + args.activation_dropout = getattr(args, "activation_dropout", 0.0) + args.activation_fn = getattr(args, "activation_fn", "relu") + args.dropout = getattr(args, "dropout", 0.1) + args.adaptive_softmax_cutoff = getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = getattr(args, "adaptive_softmax_dropout", 0) + args.share_decoder_input_output_embed = getattr( + args, "share_decoder_input_output_embed", False + ) + args.share_all_embeddings = getattr(args, "share_all_embeddings", False) + args.no_token_positional_embeddings = getattr( + args, "no_token_positional_embeddings", False + ) + args.adaptive_input = getattr(args, "adaptive_input", False) + args.no_cross_attention = getattr(args, "no_cross_attention", False) + args.cross_self_attention = getattr(args, "cross_self_attention", False) + + args.decoder_output_dim = getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = getattr(args, "decoder_input_dim", args.decoder_embed_dim) + + args.no_scale_embedding = getattr(args, "no_scale_embedding", False) + args.layernorm_embedding = getattr(args, "layernorm_embedding", False) + args.tie_adaptive_weights = getattr(args, "tie_adaptive_weights", False) + args.checkpoint_activations = getattr(args, "checkpoint_activations", False) + args.offload_activations = getattr(args, "offload_activations", False) + if args.offload_activations: + args.checkpoint_activations = True + args.encoder_layers_to_keep = getattr(args, "encoder_layers_to_keep", None) + args.decoder_layers_to_keep = getattr(args, "decoder_layers_to_keep", None) + args.encoder_layerdrop = getattr(args, "encoder_layerdrop", 0) + args.decoder_layerdrop = getattr(args, "decoder_layerdrop", 0) + args.quant_noise_pq = getattr(args, "quant_noise_pq", 0) + args.quant_noise_pq_block_size = getattr(args, "quant_noise_pq_block_size", 8) + args.quant_noise_scalar = getattr(args, "quant_noise_scalar", 0) + + +@register_model_architecture("transformer", "transformer_iwslt_de_en") +def transformer_iwslt_de_en(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 512) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 1024) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 4) + args.encoder_layers = getattr(args, "encoder_layers", 6) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 512) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 1024) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 4) + args.decoder_layers = getattr(args, "decoder_layers", 6) + base_architecture(args) + + +@register_model_architecture("transformer", "transformer_wmt_en_de") +def transformer_wmt_en_de(args): + base_architecture(args) + + +# parameters used in the "Attention Is All You Need" paper (Vaswani et al., 2017) +@register_model_architecture("transformer", "transformer_vaswani_wmt_en_de_big") +def transformer_vaswani_wmt_en_de_big(args): + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4096) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 16) + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", False) + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 1024) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 4096) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 16) + args.dropout = getattr(args, "dropout", 0.3) + base_architecture(args) + + +@register_model_architecture("transformer", "transformer_vaswani_wmt_en_fr_big") +def transformer_vaswani_wmt_en_fr_big(args): + args.dropout = getattr(args, "dropout", 0.1) + transformer_vaswani_wmt_en_de_big(args) + + +@register_model_architecture("transformer", "transformer_wmt_en_de_big") +def transformer_wmt_en_de_big(args): + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + transformer_vaswani_wmt_en_de_big(args) + + +# default parameters used in tensor2tensor implementation +@register_model_architecture("transformer", "transformer_wmt_en_de_big_t2t") +def transformer_wmt_en_de_big_t2t(args): + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", True) + args.decoder_normalize_before = getattr(args, "decoder_normalize_before", True) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.activation_dropout = getattr(args, "activation_dropout", 0.1) + transformer_vaswani_wmt_en_de_big(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer_align.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer_align.py new file mode 100644 index 00000000..eaf585bd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer_align.py @@ -0,0 +1,93 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.models import register_model, register_model_architecture +from fairseq.models.transformer import ( + TransformerModel, + base_architecture, + transformer_wmt_en_de_big, +) + + +@register_model("transformer_align") +class TransformerAlignModel(TransformerModel): + """ + See "Jointly Learning to Align and Translate with Transformer + Models" (Garg et al., EMNLP 2019). + """ + + def __init__(self, encoder, decoder, args): + super().__init__(args, encoder, decoder) + self.alignment_heads = args.alignment_heads + self.alignment_layer = args.alignment_layer + self.full_context_alignment = args.full_context_alignment + + @staticmethod + def add_args(parser): + # fmt: off + super(TransformerAlignModel, TransformerAlignModel).add_args(parser) + parser.add_argument('--alignment-heads', type=int, metavar='D', + help='Number of cross attention heads per layer to supervised with alignments') + parser.add_argument('--alignment-layer', type=int, metavar='D', + help='Layer number which has to be supervised. 0 corresponding to the bottommost layer.') + parser.add_argument('--full-context-alignment', action='store_true', + help='Whether or not alignment is supervised conditioned on the full target context.') + # fmt: on + + @classmethod + def build_model(cls, args, task): + # set any default arguments + transformer_align(args) + + transformer_model = TransformerModel.build_model(args, task) + return TransformerAlignModel( + transformer_model.encoder, transformer_model.decoder, args + ) + + def forward(self, src_tokens, src_lengths, prev_output_tokens): + encoder_out = self.encoder(src_tokens, src_lengths) + return self.forward_decoder(prev_output_tokens, encoder_out) + + def forward_decoder( + self, + prev_output_tokens, + encoder_out=None, + incremental_state=None, + features_only=False, + **extra_args, + ): + attn_args = { + "alignment_layer": self.alignment_layer, + "alignment_heads": self.alignment_heads, + } + decoder_out = self.decoder(prev_output_tokens, encoder_out, **attn_args) + + if self.full_context_alignment: + attn_args["full_context_alignment"] = self.full_context_alignment + _, alignment_out = self.decoder( + prev_output_tokens, + encoder_out, + features_only=True, + **attn_args, + **extra_args, + ) + decoder_out[1]["attn"] = alignment_out["attn"] + + return decoder_out + + +@register_model_architecture("transformer_align", "transformer_align") +def transformer_align(args): + args.alignment_heads = getattr(args, "alignment_heads", 1) + args.alignment_layer = getattr(args, "alignment_layer", 4) + args.full_context_alignment = getattr(args, "full_context_alignment", False) + base_architecture(args) + + +@register_model_architecture("transformer_align", "transformer_wmt_en_de_big_align") +def transformer_wmt_en_de_big_align(args): + args.alignment_heads = getattr(args, "alignment_heads", 1) + args.alignment_layer = getattr(args, "alignment_layer", 4) + transformer_wmt_en_de_big(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer_from_pretrained_xlm.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer_from_pretrained_xlm.py new file mode 100644 index 00000000..236d9942 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer_from_pretrained_xlm.py @@ -0,0 +1,152 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import os +from typing import Any, Dict + +from fairseq import checkpoint_utils +from fairseq.data.legacy.masked_lm_dictionary import MaskedLMDictionary +from fairseq.models import register_model, register_model_architecture +from fairseq.models.transformer import ( + TransformerDecoder, + TransformerEncoder, + TransformerModel, + base_architecture as transformer_base_architecture, +) + + +@register_model("transformer_from_pretrained_xlm") +class TransformerFromPretrainedXLMModel(TransformerModel): + @staticmethod + def add_args(parser): + """Add model-specific arguments to the parser.""" + TransformerModel.add_args(parser) + parser.add_argument( + "--pretrained-xlm-checkpoint", + type=str, + metavar="STR", + help="XLM model to use for initializing transformer encoder and/or decoder", + ) + parser.add_argument( + "--init-encoder-only", + action="store_true", + help="if set, don't load the XLM weights and embeddings into decoder", + ) + parser.add_argument( + "--init-decoder-only", + action="store_true", + help="if set, don't load the XLM weights and embeddings into encoder", + ) + + @classmethod + def build_model(self, args, task, cls_dictionary=MaskedLMDictionary): + assert hasattr(args, "pretrained_xlm_checkpoint"), ( + "You must specify a path for --pretrained-xlm-checkpoint to use " + "--arch transformer_from_pretrained_xlm" + ) + assert isinstance(task.source_dictionary, cls_dictionary) and isinstance( + task.target_dictionary, cls_dictionary + ), ( + "You should use a MaskedLMDictionary when using --arch " + "transformer_from_pretrained_xlm because the pretrained XLM model " + "was trained using data binarized with MaskedLMDictionary. " + "For translation, you may want to use --task " + "translation_from_pretrained_xlm" + ) + assert not ( + getattr(args, "init_encoder_only", False) + and getattr(args, "init_decoder_only", False) + ), "Only one of --init-encoder-only and --init-decoder-only can be set." + return super().build_model(args, task) + + @classmethod + def build_encoder(cls, args, src_dict, embed_tokens): + return TransformerEncoderFromPretrainedXLM(args, src_dict, embed_tokens) + + @classmethod + def build_decoder(cls, args, tgt_dict, embed_tokens): + return TransformerDecoderFromPretrainedXLM(args, tgt_dict, embed_tokens) + + +def upgrade_state_dict_with_xlm_weights( + state_dict: Dict[str, Any], pretrained_xlm_checkpoint: str +) -> Dict[str, Any]: + """ + Load XLM weights into a Transformer encoder or decoder model. + + Args: + state_dict: state dict for either TransformerEncoder or + TransformerDecoder + pretrained_xlm_checkpoint: checkpoint to load XLM weights from + + Raises: + AssertionError: If architecture (num layers, attention heads, etc.) + does not match between the current Transformer encoder or + decoder and the pretrained_xlm_checkpoint + """ + if not os.path.exists(pretrained_xlm_checkpoint): + raise IOError("Model file not found: {}".format(pretrained_xlm_checkpoint)) + + state = checkpoint_utils.load_checkpoint_to_cpu(pretrained_xlm_checkpoint) + xlm_state_dict = state["model"] + for key in xlm_state_dict.keys(): + + for search_key in ["embed_tokens", "embed_positions", "layers"]: + if search_key in key: + subkey = key[key.find(search_key) :] + assert subkey in state_dict, ( + "{} Transformer encoder / decoder " + "state_dict does not contain {}. Cannot " + "load {} from pretrained XLM checkpoint " + "{} into Transformer.".format( + str(state_dict.keys()), subkey, key, pretrained_xlm_checkpoint + ) + ) + + state_dict[subkey] = xlm_state_dict[key] + return state_dict + + +class TransformerEncoderFromPretrainedXLM(TransformerEncoder): + def __init__(self, args, dictionary, embed_tokens): + super().__init__(args, dictionary, embed_tokens) + if getattr(args, "init_decoder_only", False): + # Don't load XLM weights for encoder if --init-decoder-only + return + + assert hasattr(args, "pretrained_xlm_checkpoint"), ( + "--pretrained-xlm-checkpoint must be specified to load Transformer " + "encoder from pretrained XLM" + ) + xlm_loaded_state_dict = upgrade_state_dict_with_xlm_weights( + state_dict=self.state_dict(), + pretrained_xlm_checkpoint=args.pretrained_xlm_checkpoint, + ) + self.load_state_dict(xlm_loaded_state_dict, strict=True) + + +class TransformerDecoderFromPretrainedXLM(TransformerDecoder): + def __init__(self, args, dictionary, embed_tokens, no_encoder_attn=False): + super().__init__(args, dictionary, embed_tokens, no_encoder_attn) + if getattr(args, "init_encoder_only", False): + # Don't load XLM weights for decoder if --init-encoder-only + return + assert hasattr(args, "pretrained_xlm_checkpoint"), ( + "--pretrained-xlm-checkpoint must be specified to load Transformer " + "decoder from pretrained XLM" + ) + + xlm_loaded_state_dict = upgrade_state_dict_with_xlm_weights( + state_dict=self.state_dict(), + pretrained_xlm_checkpoint=args.pretrained_xlm_checkpoint, + ) + self.load_state_dict(xlm_loaded_state_dict, strict=True) + + +@register_model_architecture( + "transformer_from_pretrained_xlm", "transformer_from_pretrained_xlm" +) +def base_architecture(args): + transformer_base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer_lm.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer_lm.py new file mode 100644 index 00000000..1e3aa72d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer_lm.py @@ -0,0 +1,607 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from dataclasses import dataclass, field +from typing import Optional + +from omegaconf import II + +from fairseq import options, utils +from fairseq.dataclass import ChoiceEnum, FairseqDataclass +from fairseq.models import ( + FairseqLanguageModel, + register_model, + register_model_architecture, +) +from fairseq.models.transformer import ( + DEFAULT_MIN_PARAMS_TO_WRAP, + Embedding, + TransformerDecoder, +) +from fairseq.modules import AdaptiveInput, CharacterTokenEmbedder +from fairseq.utils import safe_getattr, safe_hasattr + +DEFAULT_MAX_TARGET_POSITIONS = 1024 + + +@dataclass +class TransformerLanguageModelConfig(FairseqDataclass): + activation_fn: ChoiceEnum(utils.get_available_activation_fns()) = field( + default="relu", metadata={"help": "activation function to use"} + ) + dropout: float = field(default=0.1, metadata={"help": "dropout probability"}) + attention_dropout: float = field( + default=0.0, metadata={"help": "dropout probability for attention weights"} + ) + activation_dropout: float = field( + default=0.0, metadata={"help": "dropout probability after activation in FFN."} + ) + relu_dropout: float = field( + default=0.0, metadata={"help": "dropout probability after activation in FFN."} + ) + decoder_embed_dim: int = field( + default=512, metadata={"help": "decoder embedding dimension"} + ) + decoder_output_dim: int = field( + default=512, metadata={"help": "decoder output dimension"} + ) + decoder_input_dim: int = field( + default=512, metadata={"help": "decoder input dimension"} + ) + decoder_ffn_embed_dim: int = field( + default=2048, metadata={"help": "decoder embedding dimension for FFN"} + ) + decoder_layers: int = field(default=6, metadata={"help": "num decoder layers"}) + decoder_attention_heads: int = field( + default=8, metadata={"help": "num decoder attention heads"} + ) + decoder_normalize_before: bool = field( + default=False, metadata={"help": "apply layernorm before each decoder block"} + ) + no_decoder_final_norm: bool = field( + default=False, + metadata={"help": "don't add an extra layernorm after the last decoder block"}, + ) + adaptive_softmax_cutoff: Optional[str] = field( + default=None, + metadata={ + "help": "comma separated list of adaptive softmax cutoff points. " + "Must be used with adaptive_loss criterion" + }, + ) + adaptive_softmax_dropout: float = field( + default=0, + metadata={"help": "sets adaptive softmax dropout for the tail projections"}, + ) + adaptive_softmax_factor: float = field( + default=4, metadata={"help": "adaptive input factor"} + ) + no_token_positional_embeddings: bool = field( + default=False, + metadata={ + "help": "if set, disables positional embeddings (outside self attention)" + }, + ) + share_decoder_input_output_embed: bool = field( + default=False, metadata={"help": "share decoder input and output embeddings"} + ) + character_embeddings: bool = field( + default=False, + metadata={ + "help": "if set, uses character embedding convolutions to produce token embeddings" + }, + ) + character_filters: str = field( + default="[(1, 64), (2, 128), (3, 192), (4, 256), (5, 256), (6, 256), (7, 256)]", + metadata={"help": "size of character embeddings"}, + ) + character_embedding_dim: int = field( + default=4, metadata={"help": "size of character embeddings"} + ) + char_embedder_highway_layers: int = field( + default=2, + metadata={"help": "number of highway layers for character token embeddder"}, + ) + adaptive_input: bool = field( + default=False, metadata={"help": "if set, uses adaptive input"} + ) + adaptive_input_factor: float = field( + default=4, metadata={"help": "adaptive input factor"} + ) + adaptive_input_cutoff: Optional[str] = field( + default=None, + metadata={"help": "comma separated list of adaptive input cutoff points."}, + ) + tie_adaptive_weights: bool = field( + default=False, + metadata={ + "help": "if set, ties the weights of adaptive softmax and adaptive input" + }, + ) + tie_adaptive_proj: bool = field( + default=False, + metadata={ + "help": "if set, ties the projection weights of adaptive softmax and adaptive input" + }, + ) + decoder_learned_pos: bool = field( + default=False, + metadata={"help": "use learned positional embeddings in the decoder"}, + ) + layernorm_embedding: bool = field( + default=False, metadata={"help": "add layernorm to embedding"} + ) + no_scale_embedding: bool = field( + default=False, metadata={"help": "if True, dont scale embeddings"} + ) + checkpoint_activations: bool = field( + default=False, metadata={"help": "checkpoint activations at each layer"} + ) + offload_activations: bool = field( + default=False, + metadata={"help": "move checkpointed activations to CPU after they are used."}, + ) + # config for "Reducing Transformer Depth on Demand with Structured Dropout" (Fan et al., 2019) + decoder_layerdrop: float = field( + default=0.0, metadata={"help": "LayerDrop probability for decoder"} + ) + decoder_layers_to_keep: Optional[str] = field( + default=None, + metadata={ + "help": "which layers to *keep* when pruning as a comma-separated list" + }, + ) + # config for Training with Quantization Noise for Extreme Model Compression ({Fan*, Stock*} et al., 2020) + quant_noise_pq: float = field( + default=0.0, + metadata={"help": "iterative PQ quantization noise at training time"}, + ) + quant_noise_pq_block_size: int = field( + default=8, + metadata={"help": "block size of quantization noise at training time"}, + ) + quant_noise_scalar: float = field( + default=0.0, + metadata={ + "help": "scalar quantization noise and scalar quantization at training time" + }, + ) + # config for Fully Sharded Data Parallel (FSDP) training + min_params_to_wrap: int = field( + default=DEFAULT_MIN_PARAMS_TO_WRAP, + metadata={ + "help": ( + "minimum number of params for a layer to be wrapped with FSDP() when " + "training with --ddp-backend=fully_sharded. Smaller values will " + "improve memory efficiency, but may make torch.distributed " + "communication less efficient due to smaller input sizes. This option " + "is set to 0 (i.e., always wrap) when --checkpoint-activations or " + "--offload-activations are passed." + ) + }, + ) + # config for "BASE Layers: Simplifying Training of Large, Sparse Models" + base_layers: Optional[int] = field( + default=0, metadata={"help": "number of BASE layers in total"} + ) + base_sublayers: Optional[int] = field( + default=1, metadata={"help": "number of sublayers in each BASE layer"} + ) + base_shuffle: Optional[int] = field( + default=1, + metadata={"help": "shuffle tokens between workers before computing assignment"}, + ) + # NormFormer + scale_fc: Optional[bool] = field( + default=False, + metadata={"help": "Insert LayerNorm between fully connected layers"}, + ) + scale_attn: Optional[bool] = field( + default=False, metadata={"help": "Insert LayerNorm after attention"} + ) + scale_heads: Optional[bool] = field( + default=False, + metadata={"help": "Learn a scale coefficient for each attention head"}, + ) + scale_resids: Optional[bool] = field( + default=False, + metadata={"help": "Learn a scale coefficient for each residual connection"}, + ) + + # xFormers arguments + decoder_xformers_att_config: Optional[str] = field( + default=None, + metadata={ + "help": "config for xFormers library attention, defined in xformers.components.attention.AttentionConfig", + }, + ) + + # options from other parts of the config + add_bos_token: bool = II("task.add_bos_token") + tokens_per_sample: int = II("task.tokens_per_sample") + max_target_positions: Optional[int] = II("task.max_target_positions") + tpu: bool = II("common.tpu") + + +@register_model("transformer_lm", dataclass=TransformerLanguageModelConfig) +class TransformerLanguageModel(FairseqLanguageModel): + @classmethod + def hub_models(cls): + def moses_fastbpe(path): + return {"path": path, "tokenizer": "moses", "bpe": "fastbpe"} + + def spm(path): + return {"path": path, "tokenizer": "space", "bpe": "sentencepiece"} + + return { + "transformer_lm.gbw.adaptive_huge": "https://dl.fbaipublicfiles.com/fairseq/models/lm/adaptive_lm_gbw_huge.tar.bz2", + "transformer_lm.wiki103.adaptive": "https://dl.fbaipublicfiles.com/fairseq/models/lm/adaptive_lm_wiki103.v2.tar.bz2", + "transformer_lm.wmt19.en": moses_fastbpe( + "https://dl.fbaipublicfiles.com/fairseq/models/lm/wmt19.en.tar.bz2" + ), + "transformer_lm.wmt19.de": moses_fastbpe( + "https://dl.fbaipublicfiles.com/fairseq/models/lm/wmt19.de.tar.bz2" + ), + "transformer_lm.wmt19.ru": moses_fastbpe( + "https://dl.fbaipublicfiles.com/fairseq/models/lm/wmt19.ru.tar.bz2" + ), + "transformer_lm.wmt20.en": spm( + "https://dl.fbaipublicfiles.com/fairseq/models/lm/wmt20.en.tar.gz" + ), + "transformer_lm.wmt20.ta": spm( + "https://dl.fbaipublicfiles.com/fairseq/models/lm/wmt20.ta.tar.gz" + ), + "transformer_lm.wmt20.iu.news": spm( + "https://dl.fbaipublicfiles.com/fairseq/models/lm/wmt20.iu.news.tar.gz" + ), + "transformer_lm.wmt20.iu.nh": spm( + "https://dl.fbaipublicfiles.com/fairseq/models/lm/wmt20.iu.nh.tar.gz" + ), + } + + def __init__(self, decoder): + super().__init__(decoder) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + if args.decoder_layers_to_keep: + args.decoder_layers = len(args.decoder_layers_to_keep.split(",")) + + if safe_getattr(args, "max_target_positions", None) is None: + args.max_target_positions = safe_getattr( + args, "tokens_per_sample", DEFAULT_MAX_TARGET_POSITIONS + ) + + if args.character_embeddings: + embed_tokens = CharacterTokenEmbedder( + task.source_dictionary, + eval(args.character_filters), + args.character_embedding_dim, + args.decoder_embed_dim, + args.char_embedder_highway_layers, + ) + elif args.adaptive_input: + embed_tokens = AdaptiveInput( + len(task.source_dictionary), + task.source_dictionary.pad(), + args.decoder_input_dim, + args.adaptive_input_factor, + args.decoder_embed_dim, + options.eval_str_list(args.adaptive_input_cutoff, type=int), + args.quant_noise_pq, + args.quant_noise_pq_block_size, + ) + else: + embed_tokens = cls.build_embedding( + args, task.source_dictionary, args.decoder_input_dim + ) + + if args.tie_adaptive_weights: + assert args.adaptive_input + assert args.adaptive_input_factor == args.adaptive_softmax_factor + assert ( + args.adaptive_softmax_cutoff == args.adaptive_input_cutoff + ), "{} != {}".format( + args.adaptive_softmax_cutoff, args.adaptive_input_cutoff + ) + assert args.decoder_input_dim == args.decoder_output_dim + + decoder = TransformerDecoder( + args, task.target_dictionary, embed_tokens, no_encoder_attn=True + ) + return cls(decoder) + + @classmethod + def build_embedding(cls, args, dictionary, embed_dim, path=None): + embed_tokens = Embedding(len(dictionary), embed_dim, dictionary.pad()) + return embed_tokens + + +def base_lm_architecture(args): + # backward compatibility for older model checkpoints + if safe_hasattr(args, "no_tie_adaptive_proj"): + # previous models defined --no-tie-adaptive-proj, so use the existence of + # that option to determine if this is an "old" model checkpoint + args.no_decoder_final_norm = True # old models always set this to True + if args.no_tie_adaptive_proj is False: + args.tie_adaptive_proj = True + if safe_hasattr(args, "decoder_final_norm"): + args.no_decoder_final_norm = not args.decoder_final_norm + + args.dropout = safe_getattr(args, "dropout", 0.1) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.0) + + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 512) + args.decoder_ffn_embed_dim = safe_getattr(args, "decoder_ffn_embed_dim", 2048) + args.decoder_layers = safe_getattr(args, "decoder_layers", 6) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 8) + args.adaptive_softmax_cutoff = safe_getattr(args, "adaptive_softmax_cutoff", None) + args.adaptive_softmax_dropout = safe_getattr(args, "adaptive_softmax_dropout", 0) + args.adaptive_softmax_factor = safe_getattr(args, "adaptive_softmax_factor", 4) + args.decoder_learned_pos = safe_getattr(args, "decoder_learned_pos", False) + args.activation_fn = safe_getattr(args, "activation_fn", "relu") + + args.decoder_layerdrop = safe_getattr(args, "decoder_layerdrop", 0) + args.decoder_layers_to_keep = safe_getattr(args, "decoder_layers_to_keep", None) + args.quant_noise_pq = safe_getattr(args, "quant_noise_pq", 0) + args.quant_noise_pq_block_size = safe_getattr(args, "quant_noise_pq_block_size", 8) + args.quant_noise_scalar = safe_getattr(args, "quant_noise_scalar", 0) + + args.base_layers = safe_getattr(args, "base_layers", 0) + args.base_sublayers = safe_getattr(args, "base_sublayers", 1) + args.base_shuffle = safe_getattr(args, "base_shuffle", False) + + args.add_bos_token = safe_getattr(args, "add_bos_token", False) + args.no_token_positional_embeddings = safe_getattr( + args, "no_token_positional_embeddings", False + ) + args.share_decoder_input_output_embed = safe_getattr( + args, "share_decoder_input_output_embed", False + ) + args.character_embeddings = safe_getattr(args, "character_embeddings", False) + + args.decoder_output_dim = safe_getattr( + args, "decoder_output_dim", args.decoder_embed_dim + ) + args.decoder_input_dim = safe_getattr( + args, "decoder_input_dim", args.decoder_embed_dim + ) + + # Model training is not stable without this + args.decoder_normalize_before = True + args.no_decoder_final_norm = safe_getattr(args, "no_decoder_final_norm", False) + + args.adaptive_input = safe_getattr(args, "adaptive_input", False) + args.adaptive_input_factor = safe_getattr(args, "adaptive_input_factor", 4) + args.adaptive_input_cutoff = safe_getattr(args, "adaptive_input_cutoff", None) + + args.tie_adaptive_weights = safe_getattr(args, "tie_adaptive_weights", False) + args.tie_adaptive_proj = safe_getattr(args, "tie_adaptive_proj", False) + + args.no_scale_embedding = safe_getattr(args, "no_scale_embedding", False) + args.layernorm_embedding = safe_getattr(args, "layernorm_embedding", False) + args.checkpoint_activations = safe_getattr(args, "checkpoint_activations", False) + args.offload_activations = safe_getattr(args, "offload_activations", False) + args.scale_fc = safe_getattr(args, "scale_fc", False) + args.scale_attn = safe_getattr(args, "scale_attn", False) + args.scale_heads = safe_getattr(args, "scale_heads", False) + args.scale_resids = safe_getattr(args, "scale_resids", False) + if args.offload_activations: + args.checkpoint_activations = True + + +@register_model_architecture("transformer_lm", "transformer_lm_big") +def transformer_lm_big(args): + args.decoder_layers = safe_getattr(args, "decoder_layers", 12) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 1024) + args.decoder_ffn_embed_dim = safe_getattr(args, "decoder_ffn_embed_dim", 4096) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 16) + base_lm_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_wiki103") +@register_model_architecture("transformer_lm", "transformer_lm_baevski_wiki103") +def transformer_lm_baevski_wiki103(args): + args.decoder_layers = safe_getattr(args, "decoder_layers", 16) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 8) + args.dropout = safe_getattr(args, "dropout", 0.3) + args.adaptive_input = safe_getattr(args, "adaptive_input", True) + args.tie_adaptive_weights = safe_getattr(args, "tie_adaptive_weights", True) + args.adaptive_input_cutoff = safe_getattr( + args, "adaptive_input_cutoff", "20000,60000" + ) + args.adaptive_softmax_cutoff = safe_getattr( + args, "adaptive_softmax_cutoff", "20000,60000" + ) + args.adaptive_softmax_dropout = safe_getattr(args, "adaptive_softmax_dropout", 0.2) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.1) + args.activation_dropout = safe_getattr(args, "activation_dropout", 0.1) + args.no_decoder_final_norm = safe_getattr(args, "no_decoder_final_norm", True) + args.tie_adaptive_proj = safe_getattr(args, "tie_adaptive_proj", True) + transformer_lm_big(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gbw") +@register_model_architecture("transformer_lm", "transformer_lm_baevski_gbw") +def transformer_lm_baevski_gbw(args): + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 512) + args.dropout = safe_getattr(args, "dropout", 0.1) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.1) + args.no_decoder_final_norm = safe_getattr(args, "no_decoder_final_norm", True) + transformer_lm_big(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt") +def transformer_lm_gpt(args): + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 768) + args.decoder_ffn_embed_dim = safe_getattr(args, "decoder_ffn_embed_dim", 3072) + args.decoder_layers = safe_getattr(args, "decoder_layers", 12) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 12) + args.dropout = safe_getattr(args, "dropout", 0.1) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.1) + args.activation_fn = safe_getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt2_small") +def transformer_lm_gpt2_small(args): + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 1024) + args.decoder_ffn_embed_dim = safe_getattr(args, "decoder_ffn_embed_dim", 4096) + args.decoder_layers = safe_getattr(args, "decoder_layers", 24) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 16) + args.dropout = safe_getattr(args, "dropout", 0.1) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.1) + args.activation_fn = safe_getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt2_tiny") +def transformer_lm_gpt2_tiny(args): + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 64) + args.decoder_ffn_embed_dim = safe_getattr(args, "decoder_ffn_embed_dim", 64) + args.decoder_layers = safe_getattr(args, "decoder_layers", 2) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 1) + args.dropout = safe_getattr(args, "dropout", 0.1) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.1) + args.activation_fn = safe_getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt2_medium") +def transformer_lm_gpt2_medium(args): + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 1280) + args.decoder_ffn_embed_dim = safe_getattr(args, "decoder_ffn_embed_dim", 5120) + args.decoder_layers = safe_getattr(args, "decoder_layers", 36) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 20) + args.dropout = safe_getattr(args, "dropout", 0.1) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.1) + args.activation_fn = safe_getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt2_big") +def transformer_lm_gpt2_big(args): + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 1600) + args.decoder_ffn_embed_dim = safe_getattr(args, "decoder_ffn_embed_dim", 6400) + args.decoder_layers = safe_getattr(args, "decoder_layers", 48) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 25) + args.dropout = safe_getattr(args, "dropout", 0.1) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.1) + args.activation_fn = safe_getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt2_big_wide") +def transformer_lm_gpt2_big_wide(args): + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 2048) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 8192) + args.decoder_layers = getattr(args, "decoder_layers", 24) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 32) + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.activation_fn = getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt2_bigger") +def transformer_lm_gpt2_bigger(args): + args.decoder_embed_dim = getattr(args, "decoder_embed_dim", 2048) + args.decoder_ffn_embed_dim = getattr(args, "decoder_ffn_embed_dim", 8192) + args.decoder_layers = getattr(args, "decoder_layers", 48) + args.decoder_attention_heads = getattr(args, "decoder_attention_heads", 32) + args.dropout = getattr(args, "dropout", 0.1) + args.attention_dropout = getattr(args, "attention_dropout", 0.1) + args.activation_fn = getattr(args, "activation_fn", "gelu") + base_lm_architecture(args) + + +def base_gpt3_architecture(args): + args.decoder_input_dim = args.decoder_embed_dim + args.decoder_output_dim = args.decoder_embed_dim + args.decoder_ffn_embed_dim = safe_getattr( + args, "decoder_ffn_embed_dim", args.decoder_embed_dim * 4 + ) + # GPT-3 used learned positional embeddings, rather than sinusoidal + args.decoder_learned_pos = safe_getattr(args, "decoder_learned_pos", True) + args.dropout = safe_getattr(args, "dropout", 0.0) + args.attention_dropout = safe_getattr(args, "attention_dropout", 0.0) + args.activation_fn = safe_getattr(args, "activation_fn", "gelu") + args.share_decoder_input_output_embed = True + base_lm_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt3_small") +def transformer_lm_gpt3_small(args): + # 125M params + args.decoder_layers = safe_getattr(args, "decoder_layers", 12) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 768) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 12) + base_gpt3_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt3_medium") +def transformer_lm_gpt3_medium(args): + # 350M params + args.decoder_layers = safe_getattr(args, "decoder_layers", 24) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 1024) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 16) + base_gpt3_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt3_large") +def transformer_lm_gpt3_large(args): + # 760M params + args.decoder_layers = safe_getattr(args, "decoder_layers", 24) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 1536) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 16) + base_gpt3_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt3_xl") +def transformer_lm_gpt3_xl(args): + # 1.3B params + args.decoder_layers = safe_getattr(args, "decoder_layers", 24) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 2048) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 32) + base_gpt3_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt3_2_7") +def transformer_lm_gpt3_2_7(args): + # 2.7B params + args.decoder_layers = safe_getattr(args, "decoder_layers", 32) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 2560) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 32) + base_gpt3_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt3_6_7") +def transformer_lm_gpt3_6_7(args): + # 6.7B params + args.decoder_layers = safe_getattr(args, "decoder_layers", 32) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 4096) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 32) + base_gpt3_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt3_13") +def transformer_lm_gpt3_13(args): + # 13B params + args.decoder_layers = safe_getattr(args, "decoder_layers", 40) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 5120) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 40) + base_gpt3_architecture(args) + + +@register_model_architecture("transformer_lm", "transformer_lm_gpt3_175") +def transformer_lm_gpt3_175(args): + # 175B params + args.decoder_layers = safe_getattr(args, "decoder_layers", 96) + args.decoder_embed_dim = safe_getattr(args, "decoder_embed_dim", 12288) + args.decoder_attention_heads = safe_getattr(args, "decoder_attention_heads", 96) + base_gpt3_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/transformer_ulm.py b/PyTorch/NLP/new-Transformer/fairseq/models/transformer_ulm.py new file mode 100644 index 00000000..0fc9ae43 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/transformer_ulm.py @@ -0,0 +1,408 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from dataclasses import dataclass, field +from fairseq.models.fairseq_decoder import FairseqDecoder +import numpy as np +from typing import Optional, Dict, Any, List +import torch +from torch import nn +from fairseq.data.data_utils import compute_mask_indices +from fairseq.dataclass import ChoiceEnum +from fairseq.models import ( + FairseqLanguageModel, + register_model, + register_model_architecture, +) +from fairseq.tasks.speech_ulm_task import SpeechUnitLanguageModelingTask +from fairseq.models.transformer import Embedding, TransformerDecoder, Linear +from fairseq.models.transformer_lm import TransformerLanguageModelConfig +from torch import Tensor + + +DEFAULT_MAX_TARGET_POSITIONS = 1024 +MASKING_DISTRIBUTION_CHOICES = ChoiceEnum(["static", "uniform", "normal", "poisson"]) + + +@dataclass +class SpeechUnitLanguageModelConfig(TransformerLanguageModelConfig): + mask_unit_seg_prob: float = field( + default=0.0, metadata={"help": "probability to mask a segment of unit sequence"} + ) + mask_unit_seg_leng: int = field( + default=5, metadata={"help": "length of unit segment mask"} + ) + mask_unit_seg_type: MASKING_DISTRIBUTION_CHOICES = field( + default="static", metadata={"help": "how to choose unit mask length"} + ) + + mask_dur_prob: float = field( + default=0.0, metadata={"help": "probability to mask entire duration sequence"} + ) + mask_dur_seg_prob: float = field( + default=0.0, + metadata={"help": "probability to mask a segment of duration sequence"}, + ) + mask_dur_seg_leng: int = field( + default=5, metadata={"help": "length of duration segment mask"} + ) + mask_dur_seg_type: MASKING_DISTRIBUTION_CHOICES = field( + default="static", metadata={"help": "how to choose duration mask length"} + ) + + mask_f0_prob: float = field( + default=0.0, metadata={"help": "probability to mask entire duration sequence"} + ) + mask_f0_seg_prob: float = field( + default=0.0, metadata={"help": "probability to mask a segment of f0 sequence"} + ) + mask_f0_seg_leng: int = field( + default=5, metadata={"help": "length of f0 segment mask"} + ) + mask_f0_seg_type: MASKING_DISTRIBUTION_CHOICES = field( + default="static", metadata={"help": "how to choose f0 mask length"} + ) + + +@register_model("transformer_ulm", dataclass=SpeechUnitLanguageModelConfig) +class TransformerUnitLanguageModel(FairseqLanguageModel): + def __init__( + self, + cfg: SpeechUnitLanguageModelConfig, + task: SpeechUnitLanguageModelingTask, + decoder: FairseqDecoder, + ): + super().__init__(decoder) + self.cfg = cfg + + self.channel_names = task.channel_names + self.channel_sizes = task.channel_sizes + + self.unit_mask_val = task.source_dictionary.unk() + self.dur_mask_val = ( + task.source_duration_dictionary.unk() if task.cfg.discrete_duration else 0 + ) + self.f0_mask_val = ( + task.source_f0_dictionary.unk() if task.cfg.discrete_f0 else 0 + ) + + self.ignore_duration_input = task.cfg.ignore_duration_input + self.ignore_f0_input = task.cfg.ignore_f0_input + + @classmethod + def build_model(cls, args, task): + base_ulm_architecture(args) + + if getattr(args, "max_target_positions", None) is None: + args.max_target_positions = getattr( + args, "tokens_per_sample", DEFAULT_MAX_TARGET_POSITIONS + ) + + embed_tokens = Embedding( + len(task.source_dictionary), + args.decoder_input_dim, + padding_idx=task.source_dictionary.pad(), + ) + embed_duration = None + if task.cfg.discrete_duration: + embed_duration = Embedding( + len(task.source_duration_dictionary), + args.decoder_input_dim, + padding_idx=0, # duration uses 0 for padding + ) + embed_f0 = None + if task.cfg.discrete_f0: + embed_f0 = Embedding( + len(task.source_f0_dictionary), + args.decoder_input_dim, + padding_idx=task.source_f0_dictionary.pad(), + ) + + decoder = MultiStreamTransformerDecoder( + args, + task.target_dictionary, + embed_tokens, + [embed_duration, embed_f0], + no_encoder_attn=True, + channel_sizes=task.channel_sizes, + ) + + return cls(args, task, decoder) + + def apply_seg_dropout(self, inp, mask_prob, mask_leng, mask_type, mask_val): + B, T = inp.size() + if mask_prob > 0: + mask_indices = compute_mask_indices( + (B, T), None, mask_prob, mask_leng, mask_type # may mask padding + ) + mask_indices = torch.from_numpy(mask_indices).to(inp.device) + inp[mask_indices] = mask_val + else: + mask_indices = torch.zeros_like(inp).bool() + return inp, mask_indices + + def apply_seq_dropout(self, inp, mask_prob, mask_val): + B, T = inp.size() + if mask_prob > 0: + mask_indices = np.random.uniform(0, 1, (B,)) < mask_prob + mask_indices = ( + torch.from_numpy(mask_indices).to(inp.device).unsqueeze(1).expand(-1, T) + ) + inp[mask_indices] = mask_val + else: + mask_indices = torch.zeros_like(inp).bool() + return inp, mask_indices + + def apply_dropout(self, src_tokens, dur_src, f0_src): + src_tokens, unit_mask = self.apply_seg_dropout( + src_tokens, + self.cfg.mask_unit_seg_prob, + self.cfg.mask_unit_seg_leng, + self.cfg.mask_unit_seg_type, + self.unit_mask_val, + ) + + dur_src, dur_mask = self.apply_seq_dropout( + dur_src, self.cfg.mask_dur_prob, self.dur_mask_val + ) + dur_src, _dur_mask = self.apply_seg_dropout( + dur_src, + self.cfg.mask_dur_seg_prob, + self.cfg.mask_dur_seg_leng, + self.cfg.mask_dur_seg_type, + self.dur_mask_val, + ) + dur_mask = dur_mask.logical_or(_dur_mask) + + f0_src, f0_mask = self.apply_seq_dropout( + f0_src, self.cfg.mask_f0_prob, self.f0_mask_val + ) + f0_src, _f0_mask = self.apply_seg_dropout( + f0_src, + self.cfg.mask_f0_seg_prob, + self.cfg.mask_f0_seg_leng, + self.cfg.mask_f0_seg_type, + self.f0_mask_val, + ) + f0_mask = f0_mask.logical_or(_f0_mask) + + return src_tokens, unit_mask, dur_src, dur_mask, f0_src, f0_mask + + def forward( + self, + src_tokens: torch.Tensor, + dur_src: torch.Tensor, + f0_src: torch.Tensor, + src_lengths: Optional[Any] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + ): + if self.ignore_duration_input: + dur_src = torch.zeros_like(dur_src) + + if self.ignore_f0_input: + f0_src = torch.zeros_like(f0_src) + + if self.training: + ( + src_tokens, + unit_mask, + dur_src, + dur_mask, + f0_src, + f0_mask, + ) = self.apply_dropout(src_tokens, dur_src, f0_src) + else: + unit_masks = dur_mask = f0_mask = None + + prediction, _ = self.decoder( + prev_output_tokens=(src_tokens, dur_src, f0_src), + incremental_state=incremental_state, + src_lengths=src_lengths, + features_only=True, + ) + + result = dict(zip(self.channel_names, prediction)) + + return result + + +def base_ulm_architecture(args): + from .transformer_lm import base_lm_architecture + + base_lm_architecture(args) + + +@register_model_architecture("transformer_ulm", "transformer_ulm_big") +def transformer_ulm_big(args): + from .transformer_lm import transformer_lm_big + + transformer_lm_big(args) + base_ulm_architecture(args) + + +@register_model_architecture("transformer_ulm", "transformer_ulm_tiny") +def transformer_ulm_tiny(args): + from .transformer_lm import transformer_lm_gpt2_tiny + + transformer_lm_gpt2_tiny(args) + base_ulm_architecture(args) + + +class MultiStreamTransformerDecoder(TransformerDecoder): + def __init__( + self, + args, + dictionary, + embed_tokens, + embed_other_list, + no_encoder_attn, + channel_sizes, + ): + super().__init__( + args, dictionary, embed_tokens, no_encoder_attn=no_encoder_attn + ) + + # embed each channel and project if dimensions do not match + self.embed_other_list = torch.nn.ModuleList(embed_other_list) + self.proj_other_list = torch.nn.ModuleList() + dim = embed_tokens.embedding_dim + for embed_other in embed_other_list: + other_dim = 1 if embed_other is None else embed_other.embedding_dim + self.proj_other_list.append( + nn.Linear(other_dim, dim) if other_dim != dim else None + ) + + # tranformer output to prediction + self.channel_sizes = channel_sizes + self.project_out_dim = Linear( + embed_tokens.embedding_dim, sum(channel_sizes), bias=False + ) + + def extract_features_scriptable( + self, + prev_output_tokens, + encoder_out: Optional[Dict[str, List[Tensor]]], + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + full_context_alignment: bool = False, + alignment_layer: Optional[int] = None, + alignment_heads: Optional[int] = None, + ): + if alignment_layer is None: + alignment_layer = self.num_layers - 1 + + # XXX: first multi-channel change start + prev_output_tokens, *other_channels = prev_output_tokens + # XXX: first multi-channel change end + + # embed positions + positions = None + if self.embed_positions is not None: + positions = self.embed_positions( + prev_output_tokens, incremental_state=incremental_state + ) + + if incremental_state is not None: + prev_output_tokens = prev_output_tokens[:, -1:] + other_channels = [o[:, -1:] for o in other_channels] + if positions is not None: + positions = positions[:, -1:] + + # embed tokens and positions + x = self.embed_scale * self.embed_tokens(prev_output_tokens) + + # XXX: second multi-channel change start + other_channels = [ + o.unsqueeze(-1).to(dtype=x.dtype) if emb is None else emb(o) + for o, emb in zip(other_channels, self.embed_other_list) + ] + other_channels = [ + o if proj_other is None else proj_other(o) + for o, proj_other in zip(other_channels, self.proj_other_list) + ] + for o in other_channels: + x = x + o + # XXX: second multi-channel change end + + if self.quant_noise is not None: + x = self.quant_noise(x) + + if self.project_in_dim is not None: + x = self.project_in_dim(x) + + if positions is not None: + x += positions + + if self.layernorm_embedding is not None: + x = self.layernorm_embedding(x) + + x = self.dropout_module(x) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + self_attn_padding_mask: Optional[Tensor] = None + if self.cross_self_attention or prev_output_tokens.eq(self.padding_idx).any(): + self_attn_padding_mask = prev_output_tokens.eq(self.padding_idx) + + # decoder layers + attn: Optional[Tensor] = None + inner_states: List[Optional[Tensor]] = [x] + for idx, layer in enumerate(self.layers): + if incremental_state is None and not full_context_alignment: + self_attn_mask = self.buffered_future_mask(x) + else: + self_attn_mask = None + + x, layer_attn, _ = layer( + x, + encoder_out["encoder_out"][0] + if (encoder_out is not None and len(encoder_out["encoder_out"]) > 0) + else None, + encoder_out["encoder_padding_mask"][0] + if ( + encoder_out is not None + and len(encoder_out["encoder_padding_mask"]) > 0 + ) + else None, + incremental_state, + self_attn_mask=self_attn_mask, + self_attn_padding_mask=self_attn_padding_mask, + need_attn=bool((idx == alignment_layer)), + need_head_weights=bool((idx == alignment_layer)), + ) + inner_states.append(x) + if layer_attn is not None and idx == alignment_layer: + attn = layer_attn.float().to(x) + + if attn is not None: + if alignment_heads is not None: + attn = attn[:alignment_heads] + + # average probabilities over heads + attn = attn.mean(dim=0) + + if self.layer_norm is not None: + x = self.layer_norm(x) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + if self.project_out_dim is not None: + x = self.project_out_dim(x) + else: + assert False + + # XXX: the last change start + result = [] + start = 0 + for channel_size in self.channel_sizes: + end = start + channel_size + result.append(x[:, :, start:end]) + start = end + assert end == x.size(-1) + # XXX: the last change end + + return result, {"attn": [attn], "inner_states": inner_states} diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/__init__.py new file mode 100644 index 00000000..06cec181 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/__init__.py @@ -0,0 +1,8 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .wav2vec import * # noqa +from .wav2vec2 import * # noqa +from .wav2vec2_asr import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/utils.py b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/utils.py new file mode 100644 index 00000000..dd52d862 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/utils.py @@ -0,0 +1,21 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +import torch.nn.functional as F + + +def pad_to_multiple(x, multiple, dim=-1, value=0): + # Inspired from https://github.com/lucidrains/local-attention/blob/master/local_attention/local_attention.py#L41 + if x is None: + return None, 0 + tsz = x.size(dim) + m = tsz / multiple + remainder = math.ceil(m) * multiple - tsz + if m.is_integer(): + return x, 0 + pad_offset = (0,) * (-1 - dim) * 2 + + return F.pad(x, (*pad_offset, 0, remainder), value=value), remainder diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec.py b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec.py new file mode 100644 index 00000000..af6604da --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec.py @@ -0,0 +1,630 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +import logging +import math +from typing import Optional, Tuple +from omegaconf import II +import sys + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq.dataclass import ChoiceEnum, FairseqDataclass +from fairseq.models import BaseFairseqModel, register_model +from fairseq.modules import ( + Fp32GroupNorm, + Fp32LayerNorm, + GumbelVectorQuantizer, + KmeansVectorQuantizer, + TransposeLast, +) +from fairseq.tasks import FairseqTask +from fairseq.utils import buffered_arange + + +logger = logging.getLogger(__name__) + + +AGGREGATOR_CHOICES = ChoiceEnum(["cnn", "gru"]) +PROJECT_FEATURES_CHOICES = ChoiceEnum(["none", "same", "new"]) +ACTIVATION_CHOICES = ChoiceEnum(["relu", "gelu"]) +VQ_TYPE_CHOICES = ChoiceEnum(["none", "gumbel", "kmeans"]) + + +@dataclass +class Wav2VecConfig(FairseqDataclass): + prediction_steps: int = field( + default=12, metadata={"help": "number of steps ahead to predict"} + ) + sample_distance: Optional[int] = field( + default=None, + metadata={ + "help": "sample distance from target. does not work properly with cross-sampling" + }, + ) + cross_sample_negatives: int = field( + default=0, metadata={"help": "num of cross sampled negatives"} + ) + num_negatives: int = field( + default=10, metadata={"help": "num of sampled negatives"} + ) + conv_feature_layers: str = field( + default="[(512, 10, 5), (512, 8, 4), (512, 4, 2), (512, 4, 2), (512, 4, 2), (512, 1, 1), (512, 1, 1), (512, 1, 1)]", + metadata={ + "help": "convolutional feature extraction layers [(dim, kernel_size, stride), ...]" + }, + ) + conv_aggregator_layers: str = field( + default="[(512, 2, 1), (512, 3, 1), (512, 4, 1), (512, 5, 1), (512, 6, 1), (512, 7, 1), (512, 8, 1), (512, 9, 1), (512, 10, 1), (512, 11, 1), (512, 12, 1), (512, 13, 1)]", + metadata={ + "help": "convolutional aggregator layers [(dim, kernel_size, stride), ...]" + }, + ) + dropout: float = field( + default=0.0, metadata={"help": "dropout to apply within the model"} + ) + dropout_features: float = field( + default=0.0, metadata={"help": "dropout to apply to the features"} + ) + dropout_agg: float = field( + default=0.0, metadata={"help": "dropout to apply after aggregation step"} + ) + aggregator: AGGREGATOR_CHOICES = field( + default="cnn", metadata={"help": "type of aggregator to use"} + ) + gru_dim: int = field(default=512, metadata={"help": "GRU dimensionality"}) + no_conv_bias: bool = field( + default=False, metadata={"help": "if set, does not learn bias for conv layers"} + ) + agg_zero_pad: bool = field( + default=False, + metadata={"help": "if set, zero pads in aggregator instead of repl pad"}, + ) + skip_connections_feat: bool = field( + default=False, + metadata={"help": "if set, adds skip connections to the feature extractor"}, + ) + skip_connections_agg: bool = field( + default=True, + metadata={"help": "if set, adds skip connections to the aggregator"}, + ) + residual_scale: float = field( + default=0.5, metadata={"help": "scales residual by sqrt(value)"} + ) + log_compression: bool = field( + default=True, + metadata={"help": "if set, adds a log compression to feature extractor"}, + ) + balanced_classes: bool = field( + default=False, + metadata={"help": "if set, loss is scaled to balance for number of negatives"}, + ) + project_features: PROJECT_FEATURES_CHOICES = field( + default="none", + metadata={ + "help": "if not none, features are projected using the (same or new) aggregator" + }, + ) + non_affine_group_norm: bool = field( + default=False, metadata={"help": "if set, group norm is not affine"} + ) + offset: str = field( + default="auto", + metadata={ + "help": "if set to 'auto', it is computed automatically from the receptive field, else set to int value" + }, + ) + activation: ACTIVATION_CHOICES = field( + default="relu", + metadata={ + "help": "if set to 'auto', it is computed automatically from the receptive field, else set to int value" + }, + ) + vq_type: VQ_TYPE_CHOICES = field( + default="none", metadata={"help": "which type of quantizer to use"} + ) + vq_vars: int = field( + default=320, + metadata={"help": "project to this many vector quantized variables per group"}, + ) + vq_groups: int = field( + default=2, metadata={"help": "number of groups of latent variables"} + ) + vq_dim: int = field( + default=0, + metadata={ + "help": "uses this dimensionality for quantized vectors. 0 to use model dim // groups" + }, + ) + vq_depth: int = field( + default=1, metadata={"help": "number of layers for vq weight projection"} + ) + combine_groups: bool = field( + default=False, metadata={"help": "if set, variables are shared among groups"} + ) + vq_temp: Tuple[float, float, float] = field( + default=(2.0, 0.5, 0.999995), + metadata={ + "help": "temperature for latent variable sampling with gumbel softmax. should be a tuple of 3 values (start, end, decay)" + }, + ) + vq_gamma: float = field( + default=0.25, + metadata={"help": "gamma parameter for kmeans style vector quantization"}, + ) + infonce: bool = II("criterion.infonce") + + +@register_model("wav2vec", dataclass=Wav2VecConfig) +class Wav2VecModel(BaseFairseqModel): + @classmethod + def build_model(cls, cfg: Wav2VecConfig, task: FairseqTask): + """Build a new model instance.""" + + model = Wav2VecModel(cfg) + logger.info(model) + return model + + def __init__(self, cfg: Wav2VecConfig): + super().__init__() + + self.prediction_steps = cfg.prediction_steps + offset = cfg.offset + + if cfg.activation == "relu": + activation = nn.ReLU() + elif cfg.activation == "gelu": + activation = nn.GELU() + else: + raise Exception("unknown activation " + cfg.activation) + + feature_enc_layers = eval(cfg.conv_feature_layers) + self.feature_extractor = ConvFeatureExtractionModel( + conv_layers=feature_enc_layers, + dropout=0.0, + log_compression=cfg.log_compression, + skip_connections=cfg.skip_connections_feat, + residual_scale=cfg.residual_scale, + non_affine_group_norm=cfg.non_affine_group_norm, + activation=activation, + ) + embed = feature_enc_layers[-1][0] + + self.vector_quantizer = None + if cfg.vq_type == "gumbel": + self.vector_quantizer = GumbelVectorQuantizer( + dim=embed, + num_vars=cfg.vq_vars, + temp=cfg.vq_temp, + groups=cfg.vq_groups, + combine_groups=cfg.combine_groups, + vq_dim=cfg.vq_dim if cfg.vq_dim > 0 else embed, + time_first=False, + activation=activation, + weight_proj_depth=cfg.vq_depth, + weight_proj_factor=2, + ) + elif cfg.vq_type == "kmeans": + self.vector_quantizer = KmeansVectorQuantizer( + dim=embed, + num_vars=cfg.vq_vars, + groups=cfg.vq_groups, + combine_groups=cfg.combine_groups, + vq_dim=cfg.vq_dim if cfg.vq_dim > 0 else embed, + time_first=False, + gamma=cfg.vq_gamma, + ) + else: + assert ( + cfg.vq_type == "none" or cfg.vq_type is None + ), "Unknown quantizer type" + + if cfg.offset == "auto": + jin = 0 + rin = 0 + for _, k, stride in feature_enc_layers: + if rin == 0: + rin = k + rin = rin + (k - 1) * jin + if jin == 0: + jin = stride + else: + jin *= stride + offset = math.ceil(rin / jin) + + offset = int(offset) + + def make_aggregator(): + if cfg.aggregator == "cnn": + agg_layers = eval(cfg.conv_aggregator_layers) + agg_dim = agg_layers[-1][0] + feature_aggregator = ConvAggegator( + conv_layers=agg_layers, + embed=embed, + dropout=cfg.dropout, + skip_connections=cfg.skip_connections_agg, + residual_scale=cfg.residual_scale, + non_affine_group_norm=cfg.non_affine_group_norm, + conv_bias=not cfg.no_conv_bias, + zero_pad=cfg.agg_zero_pad, + activation=activation, + ) + elif cfg.aggregator == "gru": + agg_dim = cfg.gru_dim + feature_aggregator = nn.Sequential( + TransposeLast(), + nn.GRU( + input_size=embed, + hidden_size=agg_dim, + num_layers=1, + dropout=cfg.dropout, + ), + TransposeLast(deconstruct_idx=0), + ) + else: + raise Exception("unknown aggregator type " + cfg.aggregator) + + return feature_aggregator, agg_dim + + self.feature_aggregator, agg_dim = make_aggregator() + + self.wav2vec_predictions = Wav2VecPredictionsModel( + in_dim=agg_dim, + out_dim=embed, + prediction_steps=cfg.prediction_steps, + n_negatives=cfg.num_negatives, + cross_sample_negatives=cfg.cross_sample_negatives, + sample_distance=cfg.sample_distance, + dropout=cfg.dropout, + offset=offset, + balanced_classes=cfg.balanced_classes, + infonce=cfg.infonce, + ) + + self.dropout_feats = nn.Dropout(p=cfg.dropout_features) + self.dropout_agg = nn.Dropout(p=cfg.dropout_agg) + + if cfg.project_features == "none": + self.project_features = None + elif cfg.project_features == "same": + self.project_features = self.feature_aggregator + elif cfg.project_features == "new": + self.project_features, _ = make_aggregator() + + def forward(self, source): + result = {} + + features = self.feature_extractor(source) + if self.vector_quantizer: + q_res = self.vector_quantizer(features) + features = q_res["x"] + for k in q_res.keys(): + if k != "x": + result[k] = q_res[k] + + x = self.dropout_feats(features) + x = self.feature_aggregator(x) + x = self.dropout_agg(x) + + if self.project_features is not None: + features = self.project_features(features) + x, targets = self.wav2vec_predictions(x, features) + result["cpc_logits"] = x + result["cpc_targets"] = targets + + return result + + def upgrade_state_dict_named(self, state_dict, name): + super().upgrade_state_dict_named(state_dict, name) + + def max_positions(self): + """Maximum length supported by the model.""" + return sys.maxsize + + def get_logits(self, net_output): + logits = net_output["cpc_logits"] + return logits + + def get_targets(self, sample, net_output): + t = net_output["cpc_targets"] + if isinstance(t, tuple): + t = t[0] + return t.contiguous() + + def get_target_weights(self, targets, net_output): + targets = net_output["cpc_targets"] + if isinstance(targets, tuple) and targets[-1] is not None: + return targets[-1] + return None + + def get_extra_losses(self, net_output): + loss = None + if "prob_perplexity" in net_output: + loss = net_output["num_vars"] - net_output["prob_perplexity"] + elif "kmeans_loss" in net_output: + loss = net_output["kmeans_loss"] + + return loss + + +def norm_block(is_layer_norm, dim, affine=True): + if is_layer_norm: + mod = nn.Sequential( + TransposeLast(), + Fp32LayerNorm(dim, elementwise_affine=affine), + TransposeLast(), + ) + else: + mod = Fp32GroupNorm(1, dim, affine=affine) + + return mod + + +class ConvFeatureExtractionModel(nn.Module): + def __init__( + self, + conv_layers, + dropout, + log_compression, + skip_connections, + residual_scale, + non_affine_group_norm, + activation, + ): + super().__init__() + + def block(n_in, n_out, k, stride): + return nn.Sequential( + nn.Conv1d(n_in, n_out, k, stride=stride, bias=False), + nn.Dropout(p=dropout), + norm_block( + is_layer_norm=False, dim=n_out, affine=not non_affine_group_norm + ), + activation, + ) + + in_d = 1 + self.conv_layers = nn.ModuleList() + for dim, k, stride in conv_layers: + self.conv_layers.append(block(in_d, dim, k, stride)) + in_d = dim + + self.log_compression = log_compression + self.skip_connections = skip_connections + self.residual_scale = math.sqrt(residual_scale) + + def forward(self, x): + # BxT -> BxCxT + x = x.unsqueeze(1) + + for conv in self.conv_layers: + residual = x + x = conv(x) + if self.skip_connections and x.size(1) == residual.size(1): + tsz = x.size(2) + r_tsz = residual.size(2) + residual = residual[..., :: r_tsz // tsz][..., :tsz] + x = (x + residual) * self.residual_scale + + if self.log_compression: + x = x.abs() + x = x + 1 + x = x.log() + + return x + + +class ZeroPad1d(nn.Module): + def __init__(self, pad_left, pad_right): + super().__init__() + self.pad_left = pad_left + self.pad_right = pad_right + + def forward(self, x): + return F.pad(x, (self.pad_left, self.pad_right)) + + +class ConvAggegator(nn.Module): + def __init__( + self, + conv_layers, + embed, + dropout, + skip_connections, + residual_scale, + non_affine_group_norm, + conv_bias, + zero_pad, + activation, + ): + super().__init__() + + def block(n_in, n_out, k, stride): + # padding dims only really make sense for stride = 1 + ka = k // 2 + kb = ka - 1 if k % 2 == 0 else ka + + pad = ( + ZeroPad1d(ka + kb, 0) if zero_pad else nn.ReplicationPad1d((ka + kb, 0)) + ) + + return nn.Sequential( + pad, + nn.Conv1d(n_in, n_out, k, stride=stride, bias=conv_bias), + nn.Dropout(p=dropout), + norm_block(False, n_out, affine=not non_affine_group_norm), + activation, + ) + + in_d = embed + self.conv_layers = nn.ModuleList() + self.residual_proj = nn.ModuleList() + for dim, k, stride in conv_layers: + if in_d != dim and skip_connections: + self.residual_proj.append(nn.Conv1d(in_d, dim, 1, bias=False)) + else: + self.residual_proj.append(None) + + self.conv_layers.append(block(in_d, dim, k, stride)) + in_d = dim + self.conv_layers = nn.Sequential(*self.conv_layers) + self.skip_connections = skip_connections + self.residual_scale = math.sqrt(residual_scale) + + def forward(self, x): + for rproj, conv in zip(self.residual_proj, self.conv_layers): + residual = x + x = conv(x) + if self.skip_connections: + if rproj is not None: + residual = rproj(residual) + x = (x + residual) * self.residual_scale + return x + + +class Wav2VecPredictionsModel(nn.Module): + def __init__( + self, + in_dim, + out_dim, + prediction_steps, + n_negatives, + cross_sample_negatives, + sample_distance, + dropout, + offset, + balanced_classes, + infonce, + ): + super().__init__() + + self.n_negatives = n_negatives + self.cross_sample_negatives = cross_sample_negatives + self.sample_distance = sample_distance + self.project_to_steps = nn.ConvTranspose2d( + in_dim, out_dim, (1, prediction_steps) + ) + self.dropout = nn.Dropout(p=dropout) + self.offset = offset + self.balanced_classes = balanced_classes + self.infonce = infonce + + def sample_negatives(self, y): + bsz, fsz, tsz = y.shape + + y = y.transpose(0, 1) # BCT -> CBT + y = y.contiguous().view(fsz, -1) # CBT => C(BxT) + + cross_high = tsz * bsz + high = tsz if self.sample_distance is None else min(tsz, self.sample_distance) + assert high > 1 + + neg_idxs = torch.randint(low=0, high=high, size=(bsz, self.n_negatives * tsz)) + + with torch.no_grad(): + if self.n_negatives > 0: + tszs = ( + buffered_arange(tsz) + .unsqueeze(-1) + .expand(-1, self.n_negatives) + .flatten() + ) + + neg_idxs = torch.randint( + low=0, high=high - 1, size=(bsz, self.n_negatives * tsz) + ) + neg_idxs[neg_idxs >= tszs] += 1 + + if self.cross_sample_negatives > 0: + tszs = ( + buffered_arange(tsz) + .unsqueeze(-1) + .expand(-1, self.cross_sample_negatives) + .flatten() + ) + + cross_neg_idxs = torch.randint( + low=0, + high=cross_high - 1, + size=(bsz, self.cross_sample_negatives * tsz), + ) + cross_neg_idxs[cross_neg_idxs >= tszs] += 1 + + if self.n_negatives > 0: + for i in range(1, bsz): + neg_idxs[i] += i * high + else: + neg_idxs = cross_neg_idxs + + if self.cross_sample_negatives > 0 and self.n_negatives > 0: + neg_idxs = torch.cat([neg_idxs, cross_neg_idxs], dim=1) + + negs = y[..., neg_idxs.view(-1)] + negs = negs.view( + fsz, bsz, self.n_negatives + self.cross_sample_negatives, tsz + ).permute( + 2, 1, 0, 3 + ) # to NxBxCxT + + return negs + + def forward(self, x, y): + + x = x.unsqueeze(-1) + x = self.project_to_steps(x) # BxCxTxS + x = self.dropout(x) + + negatives = self.sample_negatives(y) + y = y.unsqueeze(0) + targets = torch.cat([y, negatives], dim=0) # Copies x B x C x T + + copies = targets.size(0) + bsz, dim, tsz, steps = x.shape + steps = min(steps, tsz - self.offset) + + predictions = x.new( + bsz * copies * (tsz - self.offset + 1) * steps + - ((steps + 1) * steps // 2) * copies * bsz + ) + if self.infonce: + labels = predictions.new_full( + (predictions.shape[0] // copies,), 0, dtype=torch.long + ) + else: + labels = torch.zeros_like(predictions) + weights = ( + torch.full_like(labels, 1 / self.n_negatives) + if self.balanced_classes and not self.infonce + else None + ) + + start = end = 0 + for i in range(steps): + offset = i + self.offset + end = start + (tsz - offset) * bsz * copies + if self.infonce: + predictions[start:end] = torch.einsum( + "bct,nbct->tbn", x[..., :-offset, i], targets[..., offset:] + ).flatten() + else: + pos_num = (end - start) // copies + predictions[start:end] = torch.einsum( + "bct,nbct->nbt", x[..., :-offset, i], targets[..., offset:] + ).flatten() + labels[start : start + pos_num] = 1.0 + if weights is not None: + weights[start : start + pos_num] = 1.0 + start = end + assert end == predictions.numel(), "{} != {}".format(end, predictions.numel()) + + if self.infonce: + predictions = predictions.view(-1, copies) + else: + if weights is not None: + labels = (labels, weights) + + return predictions, labels diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec2.py b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec2.py new file mode 100644 index 00000000..8214bc8e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec2.py @@ -0,0 +1,1284 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass, field +from typing import List, Tuple + +import numpy as np +import torch +import torch.nn as nn +import torch.nn.functional as F + +from fairseq import utils +from fairseq.data.data_utils import compute_mask_indices +from fairseq.dataclass import ChoiceEnum, FairseqDataclass +from fairseq.distributed import fsdp_wrap +from fairseq.models import BaseFairseqModel, register_model +from fairseq.modules import ( + Fp32GroupNorm, + Fp32LayerNorm, + GradMultiply, + GumbelVectorQuantizer, + LayerNorm, + MultiheadAttention, + RelPositionalEncoding, + SamePad, + TransposeLast, +) +from fairseq.modules.checkpoint_activations import checkpoint_wrapper +from fairseq.modules.conformer_layer import ConformerWav2Vec2EncoderLayer +from fairseq.modules.transformer_sentence_encoder import init_bert_params +from fairseq.utils import buffered_arange, index_put, is_xla_tensor + +from .utils import pad_to_multiple + +EXTRACTOR_MODE_CHOICES = ChoiceEnum(["default", "layer_norm"]) +MASKING_DISTRIBUTION_CHOICES = ChoiceEnum(["static", "uniform", "normal", "poisson"]) +LAYER_TYPE_CHOICES = ChoiceEnum(["transformer", "conformer"]) + + +@dataclass +class Wav2Vec2Config(FairseqDataclass): + extractor_mode: EXTRACTOR_MODE_CHOICES = field( + default="default", + metadata={ + "help": "mode for feature extractor. default has a single group norm with d " + "groups in the first conv block, whereas layer_norm has layer norms in " + "every block (meant to use with normalize=True)" + }, + ) + encoder_layers: int = field( + default=12, metadata={"help": "num encoder layers in the transformer"} + ) + encoder_embed_dim: int = field( + default=768, metadata={"help": "encoder embedding dimension"} + ) + encoder_ffn_embed_dim: int = field( + default=3072, metadata={"help": "encoder embedding dimension for FFN"} + ) + encoder_attention_heads: int = field( + default=12, metadata={"help": "num encoder attention heads"} + ) + activation_fn: ChoiceEnum(utils.get_available_activation_fns()) = field( + default="gelu", metadata={"help": "activation function to use"} + ) + layer_type: LAYER_TYPE_CHOICES = field( + default="transformer", metadata={"help": "layer type in encoder"} + ) + # dropouts + dropout: float = field( + default=0.1, metadata={"help": "dropout probability for the transformer"} + ) + attention_dropout: float = field( + default=0.1, metadata={"help": "dropout probability for attention weights"} + ) + activation_dropout: float = field( + default=0.0, metadata={"help": "dropout probability after activation in FFN"} + ) + encoder_layerdrop: float = field( + default=0.0, metadata={"help": "probability of dropping a tarnsformer layer"} + ) + dropout_input: float = field( + default=0.0, + metadata={"help": "dropout to apply to the input (after feat extr)"}, + ) + dropout_features: float = field( + default=0.0, + metadata={"help": "dropout to apply to the features (after feat extr)"}, + ) + + final_dim: int = field( + default=0, + metadata={ + "help": "project final representations and targets to this many dimensions." + "set to encoder_embed_dim is <= 0" + }, + ) + layer_norm_first: bool = field( + default=False, metadata={"help": "apply layernorm first in the transformer"} + ) + conv_feature_layers: str = field( + default="[(512, 10, 5)] + [(512, 3, 2)] * 4 + [(512,2,2)] + [(512,2,2)]", + metadata={ + "help": "string describing convolutional feature extraction layers in form of a python list that contains " + "[(dim, kernel_size, stride), ...]" + }, + ) + conv_bias: bool = field( + default=False, metadata={"help": "include bias in conv encoder"} + ) + logit_temp: float = field( + default=0.1, metadata={"help": "temperature to divide logits by"} + ) + quantize_targets: bool = field( + default=False, metadata={"help": "use quantized targets"} + ) + quantize_input: bool = field( + default=False, metadata={"help": "use quantized inputs"} + ) + same_quantizer: bool = field( + default=False, metadata={"help": "use same quantizer for inputs and targets"} + ) + target_glu: bool = field( + default=False, metadata={"help": "adds projection + glu to targets"} + ) + feature_grad_mult: float = field( + default=1.0, metadata={"help": "multiply feature extractor var grads by this"} + ) + quantizer_depth: int = field( + default=1, + metadata={"help": "number of quantizer layers"}, + ) + quantizer_factor: int = field( + default=3, + metadata={ + "help": "dimensionality increase for inner quantizer layers (if depth > 1)" + }, + ) + latent_vars: int = field( + default=320, + metadata={"help": "number of latent variables V in each group of the codebook"}, + ) + latent_groups: int = field( + default=2, + metadata={"help": "number of groups G of latent variables in the codebook"}, + ) + latent_dim: int = field( + default=0, + metadata={ + "help": "if > 0, uses this dimensionality for latent variables. " + "otherwise uses final_dim / latent_groups" + }, + ) + + # masking + mask_length: int = field(default=10, metadata={"help": "mask length"}) + mask_prob: float = field( + default=0.65, metadata={"help": "probability of replacing a token with mask"} + ) + mask_selection: MASKING_DISTRIBUTION_CHOICES = field( + default="static", metadata={"help": "how to choose mask length"} + ) + mask_other: float = field( + default=0, + metadata={ + "help": "secondary mask argument (used for more complex distributions), " + "see help in compute_mask_indices" + }, + ) + no_mask_overlap: bool = field( + default=False, metadata={"help": "whether to allow masks to overlap"} + ) + mask_min_space: int = field( + default=1, + metadata={"help": "min space between spans (if no overlap is enabled)"}, + ) + require_same_masks: bool = field( + default=True, + metadata={ + "help": "whether to number of masked timesteps must be the same across all " + "examples in a batch" + }, + ) + mask_dropout: float = field( + default=0.0, + metadata={"help": "percent of masks to unmask for each sample"}, + ) + + # channel masking + mask_channel_length: int = field( + default=10, metadata={"help": "length of the mask for features (channels)"} + ) + mask_channel_prob: float = field( + default=0.0, metadata={"help": "probability of replacing a feature with 0"} + ) + mask_channel_before: bool = False + mask_channel_selection: MASKING_DISTRIBUTION_CHOICES = field( + default="static", + metadata={"help": "how to choose mask length for channel masking"}, + ) + mask_channel_other: float = field( + default=0, + metadata={ + "help": "secondary mask argument (used for more complex distributions), " + "see help in compute_mask_indicesh" + }, + ) + no_mask_channel_overlap: bool = field( + default=False, metadata={"help": "whether to allow channel masks to overlap"} + ) + mask_channel_min_space: int = field( + default=1, + metadata={"help": "min space between spans (if no overlap is enabled)"}, + ) + + # negative selection + num_negatives: int = field( + default=100, + metadata={"help": "number of negative examples from the same sample"}, + ) + negatives_from_everywhere: bool = field( + default=False, + metadata={"help": "sample negatives from everywhere, not just masked states"}, + ) + cross_sample_negatives: int = field( + default=0, metadata={"help": "number of negative examples from the any sample"} + ) + codebook_negatives: int = field( + default=0, metadata={"help": "number of negative examples codebook"} + ) + + # positional embeddings + conv_pos: int = field( + default=128, + metadata={"help": "number of filters for convolutional positional embeddings"}, + ) + conv_pos_groups: int = field( + default=16, + metadata={"help": "number of groups for convolutional positional embedding"}, + ) + pos_conv_depth: int = field( + default=1, + metadata={"help": "depth of positional encoder network"}, + ) + + latent_temp: Tuple[float, float, float] = field( + default=(2, 0.5, 0.999995), + metadata={ + "help": "temperature for latent variable sampling. " + "can be tuple of 3 values (start, end, decay)" + }, + ) + max_positions: int = field(default=100000, metadata={"help": "Max positions"}) + checkpoint_activations: bool = field( + default=False, + metadata={"help": "recompute activations and save memory for extra compute"}, + ) + + # FP16 optimization + required_seq_len_multiple: int = field( + default=2, + metadata={ + "help": "pad the input to encoder such that the sequence length is divisible by multiple" + }, + ) + crop_seq_to_multiple: int = field( + default=1, + metadata={ + "help": "crop convolutional feature extractor output such that the sequence length is divisible by multiple" + }, + ) + + # Conformer + depthwise_conv_kernel_size: int = field( + default=31, + metadata={ + "help": "depthwise-conv-kernel-size for convolution in conformer layer" + }, + ) + attn_type: str = field( + default="", + metadata={"help": "if espnet use ESPNET MHA"}, + ) + pos_enc_type: str = field( + default="abs", + metadata={"help": "Positional encoding type to use in conformer"}, + ) + fp16: bool = field(default=False, metadata={"help": "If fp16 is being used"}) + + +@register_model("wav2vec2", dataclass=Wav2Vec2Config) +class Wav2Vec2Model(BaseFairseqModel): + def __init__(self, cfg: Wav2Vec2Config): + super().__init__() + self.cfg = cfg + + feature_enc_layers = eval(cfg.conv_feature_layers) + self.embed = feature_enc_layers[-1][0] + + self.feature_extractor = ConvFeatureExtractionModel( + conv_layers=feature_enc_layers, + dropout=0.0, + mode=cfg.extractor_mode, + conv_bias=cfg.conv_bias, + ) + + self.post_extract_proj = ( + nn.Linear(self.embed, cfg.encoder_embed_dim) + if self.embed != cfg.encoder_embed_dim and not cfg.quantize_input + else None + ) + + self.crop_seq_to_multiple = cfg.crop_seq_to_multiple + + self.mask_prob = cfg.mask_prob + self.mask_selection = cfg.mask_selection + self.mask_other = cfg.mask_other + self.mask_length = cfg.mask_length + self.no_mask_overlap = cfg.no_mask_overlap + self.mask_min_space = cfg.mask_min_space + + self.mask_channel_prob = cfg.mask_channel_prob + self.mask_channel_before = cfg.mask_channel_before + self.mask_channel_selection = cfg.mask_channel_selection + self.mask_channel_other = cfg.mask_channel_other + self.mask_channel_length = cfg.mask_channel_length + self.no_mask_channel_overlap = cfg.no_mask_channel_overlap + self.mask_channel_min_space = cfg.mask_channel_min_space + + self.dropout_input = nn.Dropout(cfg.dropout_input) + self.dropout_features = nn.Dropout(cfg.dropout_features) + + self.feature_grad_mult = cfg.feature_grad_mult + + self.quantizer = None + self.input_quantizer = None + + self.n_negatives = cfg.num_negatives + self.cross_sample_negatives = cfg.cross_sample_negatives + self.codebook_negatives = cfg.codebook_negatives + self.negatives_from_everywhere = cfg.negatives_from_everywhere + + self.logit_temp = cfg.logit_temp + + final_dim = cfg.final_dim if cfg.final_dim > 0 else cfg.encoder_embed_dim + + if cfg.quantize_targets: + vq_dim = cfg.latent_dim if cfg.latent_dim > 0 else final_dim + self.quantizer = GumbelVectorQuantizer( + dim=self.embed, + num_vars=cfg.latent_vars, + temp=cfg.latent_temp, + groups=cfg.latent_groups, + combine_groups=False, + vq_dim=vq_dim, + time_first=True, + weight_proj_depth=cfg.quantizer_depth, + weight_proj_factor=cfg.quantizer_factor, + ) + self.project_q = nn.Linear(vq_dim, final_dim) + else: + self.project_q = nn.Linear(self.embed, final_dim) + + if cfg.quantize_input: + if cfg.same_quantizer and self.quantizer is not None: + vq_dim = final_dim + self.input_quantizer = self.quantizer + else: + vq_dim = cfg.latent_dim if cfg.latent_dim > 0 else cfg.encoder_embed_dim + self.input_quantizer = GumbelVectorQuantizer( + dim=self.embed, + num_vars=cfg.latent_vars, + temp=cfg.latent_temp, + groups=cfg.latent_groups, + combine_groups=False, + vq_dim=vq_dim, + time_first=True, + weight_proj_depth=cfg.quantizer_depth, + weight_proj_factor=cfg.quantizer_factor, + ) + self.project_inp = nn.Linear(vq_dim, cfg.encoder_embed_dim) + + self.mask_emb = nn.Parameter( + torch.FloatTensor(cfg.encoder_embed_dim).uniform_() + ) + encoder_cls = TransformerEncoder + if cfg.layer_type == "conformer" and cfg.pos_enc_type in ["rel_pos", "rope"]: + encoder_cls = ConformerEncoder + + self.encoder = encoder_cls(cfg) + self.layer_norm = LayerNorm(self.embed) + + self.target_glu = None + if cfg.target_glu: + self.target_glu = nn.Sequential( + nn.Linear(final_dim, final_dim * 2), nn.GLU() + ) + + self.final_proj = nn.Linear(cfg.encoder_embed_dim, final_dim) + + def upgrade_state_dict_named(self, state_dict, name): + super().upgrade_state_dict_named(state_dict, name) + """Upgrade a (possibly old) state dict for new versions of fairseq.""" + return state_dict + + @classmethod + def build_model(cls, cfg: Wav2Vec2Config, task=None): + """Build a new model instance.""" + + return cls(cfg) + + def apply_mask( + self, + x, + padding_mask, + mask_indices=None, + mask_channel_indices=None, + ): + B, T, C = x.shape + + if self.mask_channel_prob > 0 and self.mask_channel_before: + mask_channel_indices = compute_mask_indices( + (B, C), + None, + self.mask_channel_prob, + self.mask_channel_length, + self.mask_channel_selection, + self.mask_channel_other, + no_overlap=self.no_mask_channel_overlap, + min_space=self.mask_channel_min_space, + ) + mask_channel_indices = ( + torch.from_numpy(mask_channel_indices) + .to(x.device) + .unsqueeze(1) + .expand(-1, T, -1) + ) + x[mask_channel_indices] = 0 + + if self.mask_prob > 0: + if mask_indices is None: + mask_indices = compute_mask_indices( + (B, T), + padding_mask, + self.mask_prob, + self.mask_length, + self.mask_selection, + self.mask_other, + min_masks=2, + no_overlap=self.no_mask_overlap, + min_space=self.mask_min_space, + require_same_masks=self.cfg.require_same_masks, + mask_dropout=self.cfg.mask_dropout, + ) + mask_indices = torch.from_numpy(mask_indices).to(x.device) + x = index_put(x, mask_indices, self.mask_emb) + else: + mask_indices = None + + if self.mask_channel_prob > 0 and not self.mask_channel_before: + if mask_channel_indices is None: + mask_channel_indices = compute_mask_indices( + (B, C), + None, + self.mask_channel_prob, + self.mask_channel_length, + self.mask_channel_selection, + self.mask_channel_other, + no_overlap=self.no_mask_channel_overlap, + min_space=self.mask_channel_min_space, + ) + mask_channel_indices = ( + torch.from_numpy(mask_channel_indices) + .to(x.device) + .unsqueeze(1) + .expand(-1, T, -1) + ) + x = index_put(x, mask_channel_indices, 0) + + return x, mask_indices + + def sample_negatives(self, y, num, padding_count=None): + + if self.n_negatives == 0 and self.cross_sample_negatives == 0: + return y.new(0) + + bsz, tsz, fsz = y.shape + y = y.view(-1, fsz) # BTC => (BxT)C + + # FIXME: what happens if padding_count is specified? + cross_high = tsz * bsz + high = tsz - (padding_count or 0) + with torch.no_grad(): + assert high > 1, f"{bsz,tsz,fsz}" + + if self.n_negatives > 0: + tszs = ( + buffered_arange(num) + .unsqueeze(-1) + .expand(-1, self.n_negatives) + .flatten() + ) + + neg_idxs = torch.randint( + low=0, high=high - 1, size=(bsz, self.n_negatives * num) + ) + neg_idxs[neg_idxs >= tszs] += 1 + + if self.cross_sample_negatives > 0: + tszs = ( + buffered_arange(num) + .unsqueeze(-1) + .expand(-1, self.cross_sample_negatives) + .flatten() + ) + + cross_neg_idxs = torch.randint( + low=0, + high=cross_high - 1, + size=(bsz, self.cross_sample_negatives * num), + ) + cross_neg_idxs[cross_neg_idxs >= tszs] += 1 + + if self.n_negatives > 0: + neg_idxs = neg_idxs + (torch.arange(bsz).unsqueeze(1) * high) + else: + neg_idxs = cross_neg_idxs + + if self.cross_sample_negatives > 0 and self.n_negatives > 0: + neg_idxs = torch.cat([neg_idxs, cross_neg_idxs], dim=1) + + negs = y[neg_idxs.view(-1)] + negs = negs.view( + bsz, num, self.n_negatives + self.cross_sample_negatives, fsz + ).permute( + 2, 0, 1, 3 + ) # to NxBxTxC + return negs, neg_idxs + + def compute_preds(self, x, y, negatives): + + neg_is_pos = (y == negatives).all(-1) + y = y.unsqueeze(0) + targets = torch.cat([y, negatives], dim=0) + + logits = torch.cosine_similarity(x.float(), targets.float(), dim=-1) + logits = logits / self.logit_temp + logits = logits.type_as(x) + + if is_xla_tensor(logits) or neg_is_pos.any(): + if not hasattr(self, "_inftensor"): + fillval = -float(2**30) + self._inftensor = ( + torch.tensor(fillval).to(x.device) + if is_xla_tensor(logits) + else float("-inf") + ) + logits[1:] = index_put(logits[1:], neg_is_pos, self._inftensor) + + return logits + + def _get_feat_extract_output_lengths(self, input_lengths: torch.LongTensor): + """ + Computes the output length of the convolutional layers + """ + + def _conv_out_length(input_length, kernel_size, stride): + return torch.floor((input_length - kernel_size) / stride + 1) + + conv_cfg_list = eval(self.cfg.conv_feature_layers) + + for i in range(len(conv_cfg_list)): + input_lengths = _conv_out_length( + input_lengths, conv_cfg_list[i][1], conv_cfg_list[i][2] + ) + + return input_lengths.to(torch.long) + + def forward( + self, + source, + padding_mask=None, + mask=True, + features_only=False, + layer=None, + mask_indices=None, + mask_channel_indices=None, + padding_count=None, + ): + + if self.feature_grad_mult > 0: + features = self.feature_extractor(source) + if self.feature_grad_mult != 1.0: + features = GradMultiply.apply(features, self.feature_grad_mult) + else: + with torch.no_grad(): + features = self.feature_extractor(source) + + features_pen = features.float().pow(2).mean() + + features = features.transpose(1, 2) + features = self.layer_norm(features) + unmasked_features = features.clone() + + if padding_mask is not None and padding_mask.any(): + input_lengths = (1 - padding_mask.long()).sum(-1) + # apply conv formula to get real output_lengths + output_lengths = self._get_feat_extract_output_lengths(input_lengths) + + padding_mask = torch.zeros( + features.shape[:2], dtype=features.dtype, device=features.device + ) + + # these two operations makes sure that all values + # before the output lengths indices are attended to + padding_mask[ + ( + torch.arange(padding_mask.shape[0], device=padding_mask.device), + output_lengths - 1, + ) + ] = 1 + padding_mask = (1 - padding_mask.flip([-1]).cumsum(-1).flip([-1])).bool() + else: + padding_mask = None + + time_steps_to_drop = features.size(1) % self.crop_seq_to_multiple + if time_steps_to_drop != 0: + features = features[:, :-time_steps_to_drop] + unmasked_features = unmasked_features[:, :-time_steps_to_drop] + if padding_mask is not None: + padding_mask = padding_mask[:, :-time_steps_to_drop] + + if self.post_extract_proj is not None: + features = self.post_extract_proj(features) + + features = self.dropout_input(features) + unmasked_features = self.dropout_features(unmasked_features) + + num_vars = None + code_ppl = None + prob_ppl = None + curr_temp = None + + if self.input_quantizer: + q = self.input_quantizer(features, produce_targets=False) + features = q["x"] + num_vars = q["num_vars"] + code_ppl = q["code_perplexity"] + prob_ppl = q["prob_perplexity"] + curr_temp = q["temp"] + features = self.project_inp(features) + + if mask: + x, mask_indices = self.apply_mask( + features, + padding_mask, + mask_indices=mask_indices, + mask_channel_indices=mask_channel_indices, + ) + if not is_xla_tensor(x) and mask_indices is not None: + # tpu-comment: reducing the size in a dynamic way causes + # too many recompilations on xla. + y = unmasked_features[mask_indices].view( + unmasked_features.size(0), -1, unmasked_features.size(-1) + ) + else: + y = unmasked_features + else: + x = features + y = unmasked_features + mask_indices = None + + x, layer_results = self.encoder(x, padding_mask=padding_mask, layer=layer) + + if features_only: + return { + "x": x, + "padding_mask": padding_mask, + "features": unmasked_features, + "layer_results": layer_results, + } + + if self.quantizer: + if self.negatives_from_everywhere: + q = self.quantizer(unmasked_features, produce_targets=False) + y = q["x"] + num_vars = q["num_vars"] + code_ppl = q["code_perplexity"] + prob_ppl = q["prob_perplexity"] + curr_temp = q["temp"] + y = self.project_q(y) + + negs, _ = self.sample_negatives( + y, + mask_indices[0].sum(), + padding_count=padding_count, + ) + y = y[mask_indices].view(y.size(0), -1, y.size(-1)) + + else: + q = self.quantizer(y, produce_targets=False) + y = q["x"] + num_vars = q["num_vars"] + code_ppl = q["code_perplexity"] + prob_ppl = q["prob_perplexity"] + curr_temp = q["temp"] + + y = self.project_q(y) + + negs, _ = self.sample_negatives( + y, + y.size(1), + padding_count=padding_count, + ) + + if self.codebook_negatives > 0: + cb_negs = self.quantizer.sample_from_codebook( + y.size(0) * y.size(1), self.codebook_negatives + ) + cb_negs = cb_negs.view( + self.codebook_negatives, y.size(0), y.size(1), -1 + ) # order doesnt matter + cb_negs = self.project_q(cb_negs) + negs = torch.cat([negs, cb_negs], dim=0) + else: + y = self.project_q(y) + + if self.negatives_from_everywhere: + negs, _ = self.sample_negatives( + unmasked_features, + y.size(1), + padding_count=padding_count, + ) + negs = self.project_q(negs) + else: + negs, _ = self.sample_negatives( + y, + y.size(1), + padding_count=padding_count, + ) + + if not is_xla_tensor(x): + # tpu-comment: reducing the size in a dynamic way causes + # too many recompilations on xla. + x = x[mask_indices].view(x.size(0), -1, x.size(-1)) + + if self.target_glu: + y = self.target_glu(y) + negs = self.target_glu(negs) + + x = self.final_proj(x) + x = self.compute_preds(x, y, negs) + + result = { + "x": x, + "padding_mask": padding_mask, + "features_pen": features_pen, + } + + if prob_ppl is not None: + result["prob_perplexity"] = prob_ppl + result["code_perplexity"] = code_ppl + result["num_vars"] = num_vars + result["temp"] = curr_temp + + return result + + def quantize(self, x): + assert self.quantizer is not None + x = self.feature_extractor(x) + x = x.transpose(1, 2) + x = self.layer_norm(x) + return self.quantizer.forward_idx(x) + + def extract_features(self, source, padding_mask, mask=False, layer=None): + res = self.forward( + source, padding_mask, mask=mask, features_only=True, layer=layer + ) + return res + + def get_logits(self, net_output): + logits = net_output["x"] + logits = logits.transpose(0, 2) + logits = logits.reshape(-1, logits.size(-1)) + return logits + + def get_targets(self, sample, net_output, expand_steps=True): + x = net_output["x"] + return x.new_zeros(x.size(1) * x.size(2), dtype=torch.long) + + def get_extra_losses(self, net_output): + pen = [] + + if "prob_perplexity" in net_output: + pen.append( + (net_output["num_vars"] - net_output["prob_perplexity"]) + / net_output["num_vars"] + ) + + if "features_pen" in net_output: + pen.append(net_output["features_pen"]) + + return pen + + def remove_pretraining_modules(self, last_layer=None): + self.quantizer = None + self.project_q = None + self.target_glu = None + self.final_proj = None + + if last_layer is not None: + self.encoder.layers = nn.ModuleList( + l for i, l in enumerate(self.encoder.layers) if i <= last_layer + ) + + +class ConvFeatureExtractionModel(nn.Module): + def __init__( + self, + conv_layers: List[Tuple[int, int, int]], + dropout: float = 0.0, + mode: str = "default", + conv_bias: bool = False, + ): + super().__init__() + + assert mode in {"default", "layer_norm"} + + def block( + n_in, + n_out, + k, + stride, + is_layer_norm=False, + is_group_norm=False, + conv_bias=False, + ): + def make_conv(): + conv = nn.Conv1d(n_in, n_out, k, stride=stride, bias=conv_bias) + nn.init.kaiming_normal_(conv.weight) + return conv + + assert ( + is_layer_norm and is_group_norm + ) == False, "layer norm and group norm are exclusive" + + if is_layer_norm: + return nn.Sequential( + make_conv(), + nn.Dropout(p=dropout), + nn.Sequential( + TransposeLast(), + Fp32LayerNorm(dim, elementwise_affine=True), + TransposeLast(), + ), + nn.GELU(), + ) + elif is_group_norm: + return nn.Sequential( + make_conv(), + nn.Dropout(p=dropout), + Fp32GroupNorm(dim, dim, affine=True), + nn.GELU(), + ) + else: + return nn.Sequential(make_conv(), nn.Dropout(p=dropout), nn.GELU()) + + in_d = 1 + self.conv_layers = nn.ModuleList() + for i, cl in enumerate(conv_layers): + assert len(cl) == 3, "invalid conv definition: " + str(cl) + (dim, k, stride) = cl + + self.conv_layers.append( + block( + in_d, + dim, + k, + stride, + is_layer_norm=mode == "layer_norm", + is_group_norm=mode == "default" and i == 0, + conv_bias=conv_bias, + ) + ) + in_d = dim + + def forward(self, x): + + # BxT -> BxCxT + x = x.unsqueeze(1) + + for conv in self.conv_layers: + x = conv(x) + + return x + + +def make_conv_pos(e, k, g): + pos_conv = nn.Conv1d( + e, + e, + kernel_size=k, + padding=k // 2, + groups=g, + ) + dropout = 0 + std = math.sqrt((4 * (1.0 - dropout)) / (k * e)) + nn.init.normal_(pos_conv.weight, mean=0, std=std) + nn.init.constant_(pos_conv.bias, 0) + + pos_conv = nn.utils.weight_norm(pos_conv, name="weight", dim=2) + pos_conv = nn.Sequential(pos_conv, SamePad(k), nn.GELU()) + + return pos_conv + + +class TransformerEncoder(nn.Module): + def build_encoder_layer(self, args: Wav2Vec2Config): + if args.layer_type == "transformer": + layer = TransformerSentenceEncoderLayer( + embedding_dim=self.embedding_dim, + ffn_embedding_dim=args.encoder_ffn_embed_dim, + num_attention_heads=args.encoder_attention_heads, + dropout=self.dropout, + attention_dropout=args.attention_dropout, + activation_dropout=args.activation_dropout, + activation_fn=args.activation_fn, + layer_norm_first=args.layer_norm_first, + ) + elif args.layer_type == "conformer": + layer = ConformerWav2Vec2EncoderLayer( + embed_dim=self.embedding_dim, + ffn_embed_dim=args.encoder_ffn_embed_dim, + attention_heads=args.encoder_attention_heads, + dropout=args.dropout, + depthwise_conv_kernel_size=args.depthwise_conv_kernel_size, + activation_fn="swish", + attn_type=args.attn_type, + use_fp16=args.fp16, + pos_enc_type="abs", + ) + layer = fsdp_wrap(layer) + if args.checkpoint_activations: + layer = checkpoint_wrapper(layer) + return layer + + def __init__(self, args: Wav2Vec2Config): + super().__init__() + + self.dropout = args.dropout + self.embedding_dim = args.encoder_embed_dim + self.required_seq_len_multiple = args.required_seq_len_multiple + + pos_conv_depth = getattr(args, "pos_conv_depth", 1) + if pos_conv_depth > 1: + num_layers = args.pos_conv_depth + k = max(3, args.conv_pos // num_layers) + + def make_conv_block(e, k, g, l): + return nn.Sequential( + *[ + nn.Sequential( + nn.Conv1d( + e, + e, + kernel_size=k, + padding=k // 2, + groups=g, + ), + SamePad(k), + TransposeLast(), + LayerNorm(e, elementwise_affine=False), + TransposeLast(), + nn.GELU(), + ) + for _ in range(l) + ] + ) + + self.pos_conv = make_conv_block( + self.embedding_dim, k, args.conv_pos_groups, num_layers + ) + + else: + self.pos_conv = make_conv_pos( + self.embedding_dim, + args.conv_pos, + args.conv_pos_groups, + ) + + self.layers = nn.ModuleList( + [self.build_encoder_layer(args) for _ in range(args.encoder_layers)] + ) + self.layer_norm_first = args.layer_norm_first + self.layer_norm = LayerNorm(self.embedding_dim) + self.layerdrop = args.encoder_layerdrop + + self.apply(init_bert_params) + + def forward(self, x, padding_mask=None, layer=None): + x, layer_results = self.extract_features(x, padding_mask, layer) + + if self.layer_norm_first and layer is None: + x = self.layer_norm(x) + + return x, layer_results + + def extract_features( + self, + x, + padding_mask=None, + tgt_layer=None, + min_layer=0, + ): + + if padding_mask is not None: + x = index_put(x, padding_mask, 0) + + x_conv = self.pos_conv(x.transpose(1, 2)) + x_conv = x_conv.transpose(1, 2) + x = x + x_conv + + if not self.layer_norm_first: + x = self.layer_norm(x) + + # pad to the sequence length dimension + x, pad_length = pad_to_multiple( + x, self.required_seq_len_multiple, dim=-2, value=0 + ) + if pad_length > 0 and padding_mask is None: + padding_mask = x.new_zeros((x.size(0), x.size(1)), dtype=torch.bool) + padding_mask[:, -pad_length:] = True + else: + padding_mask, _ = pad_to_multiple( + padding_mask, self.required_seq_len_multiple, dim=-1, value=True + ) + x = F.dropout(x, p=self.dropout, training=self.training) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + layer_results = [] + r = None + for i, layer in enumerate(self.layers): + dropout_probability = np.random.random() if self.layerdrop > 0 else 1 + if not self.training or (dropout_probability > self.layerdrop): + x, (z, lr) = layer( + x, self_attn_padding_mask=padding_mask, need_weights=False + ) + if i >= min_layer: + layer_results.append((x, z, lr)) + if i == tgt_layer: + r = x + break + + if r is not None: + x = r + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + # undo paddding + if pad_length > 0: + x = x[:, :-pad_length] + + def undo_pad(a, b, c): + return ( + a[:-pad_length], + b[:-pad_length] if b is not None else b, + c[:-pad_length], + ) + + layer_results = [undo_pad(*u) for u in layer_results] + + return x, layer_results + + def max_positions(self): + """Maximum output length supported by the encoder.""" + return self.args.max_positions + + def upgrade_state_dict_named(self, state_dict, name): + """Upgrade a (possibly old) state dict for new versions of fairseq.""" + return state_dict + + +class ConformerEncoder(TransformerEncoder): + def build_encoder_layer(self, args): + layer = ConformerWav2Vec2EncoderLayer( + embed_dim=self.embedding_dim, + ffn_embed_dim=args.encoder_ffn_embed_dim, + attention_heads=args.encoder_attention_heads, + dropout=args.dropout, + depthwise_conv_kernel_size=args.depthwise_conv_kernel_size, + activation_fn="swish", + attn_type=args.attn_type, + pos_enc_type=args.pos_enc_type, + use_fp16=args.fp16, # only used for rope + ) + layer = fsdp_wrap(layer) + if args.checkpoint_activations: + layer = checkpoint_wrapper(layer) + return layer + + def __init__(self, args): + super().__init__(args) + self.args = args + self.dropout = args.dropout + self.embedding_dim = args.encoder_embed_dim + self.pos_enc_type = args.pos_enc_type + max_source_positions = self.max_positions() + + if self.pos_enc_type == "rel_pos": + self.embed_positions = RelPositionalEncoding( + max_source_positions, self.embedding_dim + ) + elif self.pos_enc_type == "rope": + self.embed_positions = None + else: + raise Exception("Unsupported positional encoding type") + + self.layers = nn.ModuleList( + [self.build_encoder_layer(args) for _ in range(args.encoder_layers)] + ) + self.layer_norm_first = args.layer_norm_first + self.layer_norm = LayerNorm(self.embedding_dim) + self.layerdrop = args.encoder_layerdrop + + self.apply(init_bert_params) + + def extract_features(self, x, padding_mask=None, tgt_layer=None): + if padding_mask is not None: + x = index_put(x, padding_mask, 0) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + # B X T X C here + position_emb = None + if self.pos_enc_type == "rel_pos": + position_emb = self.embed_positions(x) + + if not self.layer_norm_first: + x = self.layer_norm(x) + + x = F.dropout(x, p=self.dropout, training=self.training) + + layer_results = [] + r = None + for i, layer in enumerate(self.layers): + dropout_probability = np.random.random() + if not self.training or (dropout_probability > self.layerdrop): + x, z = layer( + x, + self_attn_padding_mask=padding_mask, + need_weights=False, + position_emb=position_emb, + ) + if tgt_layer is not None: + layer_results.append((x, z)) + if i == tgt_layer: + r = x + break + + if r is not None: + x = r + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + return x, layer_results + + +class TransformerSentenceEncoderLayer(nn.Module): + """ + Implements a Transformer Encoder Layer used in BERT/XLM style pre-trained + models. + """ + + def __init__( + self, + embedding_dim: float = 768, + ffn_embedding_dim: float = 3072, + num_attention_heads: int = 8, + dropout: float = 0.1, + attention_dropout: float = 0.1, + activation_dropout: float = 0.1, + activation_fn: str = "relu", + layer_norm_first: bool = False, + ) -> None: + + super().__init__() + # Initialize parameters + self.embedding_dim = embedding_dim + self.dropout = dropout + self.activation_dropout = activation_dropout + + # Initialize blocks + self.activation_fn = utils.get_activation_fn(activation_fn) + self.self_attn = MultiheadAttention( + self.embedding_dim, + num_attention_heads, + dropout=attention_dropout, + self_attention=True, + ) + + self.dropout1 = nn.Dropout(dropout) + self.dropout2 = nn.Dropout(self.activation_dropout) + self.dropout3 = nn.Dropout(dropout) + + self.layer_norm_first = layer_norm_first + + # layer norm associated with the self attention layer + self.self_attn_layer_norm = LayerNorm(self.embedding_dim) + self.fc1 = nn.Linear(self.embedding_dim, ffn_embedding_dim) + self.fc2 = nn.Linear(ffn_embedding_dim, self.embedding_dim) + + # layer norm associated with the position wise feed-forward NN + self.final_layer_norm = LayerNorm(self.embedding_dim) + + def forward( + self, + x: torch.Tensor, + self_attn_mask: torch.Tensor = None, + self_attn_padding_mask: torch.Tensor = None, + need_weights: bool = False, + att_args=None, + ): + """ + LayerNorm is applied either before or after the self-attention/ffn + modules similar to the original Transformer imlementation. + """ + residual = x + + if self.layer_norm_first: + x = self.self_attn_layer_norm(x) + x, attn = self.self_attn( + query=x, + key=x, + value=x, + key_padding_mask=self_attn_padding_mask, + attn_mask=self_attn_mask, + need_weights=False, + ) + x = self.dropout1(x) + x = residual + x + + residual = x + x = self.final_layer_norm(x) + x = self.activation_fn(self.fc1(x)) + x = self.dropout2(x) + x = self.fc2(x) + + layer_result = x + + x = self.dropout3(x) + x = residual + x + else: + x, attn = self.self_attn( + query=x, + key=x, + value=x, + key_padding_mask=self_attn_padding_mask, + need_weights=False, + ) + + x = self.dropout1(x) + x = residual + x + + x = self.self_attn_layer_norm(x) + + residual = x + x = self.activation_fn(self.fc1(x)) + x = self.dropout2(x) + x = self.fc2(x) + + layer_result = x + + x = self.dropout3(x) + x = residual + x + x = self.final_layer_norm(x) + + return x, (attn, layer_result) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec2_asr.py b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec2_asr.py new file mode 100644 index 00000000..08d875a0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/wav2vec/wav2vec2_asr.py @@ -0,0 +1,748 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import contextlib +import copy +import logging +import math +import re +from argparse import Namespace +from dataclasses import dataclass, field +from typing import Any, Optional + +import numpy as np +import torch +import torch.nn as nn +import torch.nn.functional as F +from omegaconf import II, MISSING, open_dict + +from fairseq import checkpoint_utils, tasks, utils +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.utils import convert_namespace_to_omegaconf +from fairseq.models import ( + BaseFairseqModel, + FairseqEncoder, + FairseqEncoderDecoderModel, + FairseqIncrementalDecoder, + register_model, +) +from fairseq.models.wav2vec.wav2vec2 import MASKING_DISTRIBUTION_CHOICES +from fairseq.modules import LayerNorm, PositionalEmbedding, TransformerDecoderLayer +from fairseq.tasks import FairseqTask + +logger = logging.getLogger(__name__) + + +@dataclass +class Wav2Vec2AsrConfig(FairseqDataclass): + w2v_path: str = field( + default=MISSING, metadata={"help": "path to wav2vec 2.0 model"} + ) + no_pretrained_weights: bool = field( + default=False, metadata={"help": "if true, does not load pretrained weights"} + ) + dropout_input: float = field( + default=0.0, + metadata={"help": "dropout to apply to the input (after feat extr)"}, + ) + final_dropout: float = field( + default=0.0, + metadata={"help": "dropout after transformer and before final projection"}, + ) + dropout: float = field( + default=0.0, metadata={"help": "dropout probability inside wav2vec 2.0 model"} + ) + attention_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability for attention weights inside wav2vec 2.0 model" + }, + ) + activation_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability after activation in FFN inside wav2vec 2.0 model" + }, + ) + conv_feature_layers: Optional[str] = field( + default="[(512, 10, 5)] + [(512, 3, 2)] * 4 + [(512,2,2)] + [(512,2,2)]", + metadata={ + "help": ( + "string describing convolutional feature extraction " + "layers in form of a python list that contains " + "[(dim, kernel_size, stride), ...]" + ), + }, + ) + encoder_embed_dim: Optional[int] = field( + default=768, metadata={"help": "encoder embedding dimension"} + ) + + # masking + apply_mask: bool = field( + default=False, metadata={"help": "apply masking during fine-tuning"} + ) + mask_length: int = field( + default=10, metadata={"help": "repeat the mask indices multiple times"} + ) + mask_prob: float = field( + default=0.5, + metadata={ + "help": "probability of replacing a token with mask (normalized by length)" + }, + ) + mask_selection: MASKING_DISTRIBUTION_CHOICES = field( + default="static", metadata={"help": "how to choose masks"} + ) + mask_other: float = field( + default=0, + metadata={ + "help": "secondary mask argument (used for more complex distributions), " + "see help in compute_mask_indices" + }, + ) + no_mask_overlap: bool = field( + default=False, metadata={"help": "whether to allow masks to overlap"} + ) + mask_min_space: Optional[int] = field( + default=1, + metadata={"help": "min space between spans (if no overlap is enabled)"}, + ) + require_same_masks: bool = field( + default=True, + metadata={ + "help": "whether to number of masked timesteps must be the same across all " + "examples in a batch" + }, + ) + mask_dropout: float = field( + default=0.0, + metadata={"help": "percent of masks to unmask for each sample"}, + ) + + # channel masking + mask_channel_length: int = field( + default=10, metadata={"help": "length of the mask for features (channels)"} + ) + mask_channel_prob: float = field( + default=0.0, metadata={"help": "probability of replacing a feature with 0"} + ) + mask_channel_selection: MASKING_DISTRIBUTION_CHOICES = field( + default="static", + metadata={"help": "how to choose mask length for channel masking"}, + ) + mask_channel_other: float = field( + default=0, + metadata={ + "help": "secondary mask argument (used for more complex distributions), " + "see help in compute_mask_indicesh" + }, + ) + no_mask_channel_overlap: bool = field( + default=False, metadata={"help": "whether to allow channel masks to overlap"} + ) + freeze_finetune_updates: int = field( + default=0, metadata={"help": "dont finetune wav2vec for this many updates"} + ) + feature_grad_mult: float = field( + default=0.0, metadata={"help": "reset feature grad mult in wav2vec 2.0 to this"} + ) + layerdrop: float = field( + default=0.0, metadata={"help": "probability of dropping a layer in wav2vec 2.0"} + ) + mask_channel_min_space: Optional[int] = field( + default=1, + metadata={"help": "min space between spans (if no overlap is enabled)"}, + ) + mask_channel_before: bool = False + normalize: bool = II("task.normalize") + data: str = II("task.data") + # this holds the loaded wav2vec args + w2v_args: Any = None + offload_activations: bool = field( + default=False, metadata={"help": "offload_activations"} + ) + min_params_to_wrap: int = field( + default=int(1e8), + metadata={ + "help": "minimum number of params for a layer to be wrapped with FSDP() when " + "training with --ddp-backend=fully_sharded. Smaller values will " + "improve memory efficiency, but may make torch.distributed " + "communication less efficient due to smaller input sizes. This option " + "is set to 0 (i.e., always wrap) when --checkpoint-activations or " + "--offload-activations are passed." + }, + ) + + checkpoint_activations: bool = field( + default=False, + metadata={"help": "recompute activations and save memory for extra compute"}, + ) + ddp_backend: str = II("distributed_training.ddp_backend") + + +@dataclass +class Wav2Vec2CtcConfig(Wav2Vec2AsrConfig): + blank_weight: float = 0 + blank_mode: str = "add" + + +@register_model("wav2vec_ctc", dataclass=Wav2Vec2CtcConfig) +class Wav2VecCtc(BaseFairseqModel): + def __init__(self, cfg: Wav2Vec2CtcConfig, w2v_encoder: BaseFairseqModel): + super().__init__() + self.cfg = cfg + self.w2v_encoder = w2v_encoder + self.blank_weight = cfg.blank_weight + self.blank_mode = cfg.blank_mode + + def upgrade_state_dict_named(self, state_dict, name): + super().upgrade_state_dict_named(state_dict, name) + return state_dict + + @classmethod + def build_model(cls, cfg: Wav2Vec2CtcConfig, task: FairseqTask): + """Build a new model instance.""" + w2v_encoder = Wav2VecEncoder(cfg, len(task.target_dictionary)) + return cls(cfg, w2v_encoder) + + def get_logits(self, net_output, normalize=False): + logits = net_output["encoder_out"] + if self.blank_weight != 0: + if self.blank_mode == "add": + logits[..., 0] += self.blank_weight + elif self.blank_mode == "set": + logits[..., 0] = self.blank_weight + else: + raise Exception(f"invalid blank mode {self.blank_mode}") + + if net_output["padding_mask"] is not None and net_output["padding_mask"].any(): + number_of_classes = logits.size(-1) + masking_tensor = torch.ones( + number_of_classes, device=logits.device + ) * float("-inf") + masking_tensor[0] = 0 + logits[net_output["padding_mask"].T] = masking_tensor.type_as(logits) + + if normalize: + logits = utils.log_softmax(logits.float(), dim=-1) + + return logits + + def get_normalized_probs(self, net_output, log_probs): + """Get normalized probabilities (or log probs) from a net's output.""" + + logits = self.get_logits(net_output) + + if log_probs: + return utils.log_softmax(logits.float(), dim=-1) + else: + return utils.softmax(logits.float(), dim=-1) + + def forward(self, **kwargs): + x = self.w2v_encoder(**kwargs) + return x + + +@dataclass +class Wav2Vec2Seq2SeqConfig(Wav2Vec2AsrConfig): + decoder_embed_dim: int = field( + default=768, metadata={"help": "decoder embedding dimension"} + ) + decoder_ffn_embed_dim: int = field( + default=3072, metadata={"help": "decoder embedding dimension for FFN"} + ) + decoder_layers: int = field(default=6, metadata={"help": "num of decoder layers"}) + decoder_layerdrop: float = field( + default=0.0, metadata={"help": "decoder layerdrop chance"} + ) + decoder_attention_heads: int = field( + default=4, metadata={"help": "num decoder attention heads"} + ) + decoder_learned_pos: bool = field( + default=False, + metadata={"help": "use learned positional embeddings in the decoder"}, + ) + decoder_normalize_before: bool = field( + default=False, metadata={"help": "apply layernorm before each decoder block"} + ) + no_token_positional_embeddings: bool = field( + default=False, + metadata={ + "help": "if set, disables positional embeddings (outside self attention)" + }, + ) + decoder_dropout: float = field( + default=0.0, metadata={"help": "dropout probability in the decoder"} + ) + decoder_attention_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability for attention weights inside the decoder" + }, + ) + decoder_activation_dropout: float = field( + default=0.0, + metadata={ + "help": "dropout probability after activation in FFN inside the decoder" + }, + ) + max_target_positions: int = field( + default=2048, metadata={"help": "max target positions"} + ) + share_decoder_input_output_embed: bool = field( + default=False, metadata={"help": "share decoder input and output embeddings"} + ) + autoregressive: bool = II("task.autoregressive") + + +@register_model("wav2vec_seq2seq", dataclass=Wav2Vec2Seq2SeqConfig) +class Wav2Vec2Seq2SeqModel(FairseqEncoderDecoderModel): + def __init__(self, encoder, decoder): + super().__init__(encoder, decoder) + + @classmethod + def build_model(cls, cfg: Wav2Vec2Seq2SeqConfig, task: FairseqTask): + """Build a new model instance.""" + + assert ( + cfg.autoregressive + ), "Please set task.autoregressive=true for seq2seq asr models" + + src_dict, tgt_dict = task.source_dictionary, task.target_dictionary + + def build_embedding(dictionary, embed_dim): + num_embeddings = len(dictionary) + padding_idx = dictionary.pad() + emb = Embedding(num_embeddings, embed_dim, padding_idx) + return emb + + decoder_embed_tokens = build_embedding(tgt_dict, cfg.decoder_embed_dim) + + encoder = cls.build_encoder(cfg) + decoder = cls.build_decoder(cfg, tgt_dict, decoder_embed_tokens) + + return Wav2Vec2Seq2SeqModel(encoder, decoder) + + @classmethod + def build_encoder(cls, cfg: Wav2Vec2AsrConfig): + return Wav2VecEncoder(cfg) + + @classmethod + def build_decoder(cls, cfg: Wav2Vec2Seq2SeqConfig, tgt_dict, embed_tokens): + return TransformerDecoder(cfg, tgt_dict, embed_tokens) + + def forward(self, **kwargs): + encoder_out = self.encoder(**kwargs) + decoder_out = self.decoder(encoder_out=encoder_out, **kwargs) + return decoder_out + + def upgrade_state_dict_named(self, state_dict, name): + super().upgrade_state_dict_named(state_dict, name) + return state_dict + + +class Wav2VecEncoder(FairseqEncoder): + def __init__(self, cfg: Wav2Vec2AsrConfig, output_size=None): + self.apply_mask = cfg.apply_mask + + arg_overrides = { + "dropout": cfg.dropout, + "activation_dropout": cfg.activation_dropout, + "dropout_input": cfg.dropout_input, + "attention_dropout": cfg.attention_dropout, + "mask_length": cfg.mask_length, + "mask_prob": cfg.mask_prob, + "require_same_masks": getattr(cfg, "require_same_masks", True), + "pct_holes": getattr(cfg, "mask_dropout", 0), + "mask_selection": cfg.mask_selection, + "mask_other": cfg.mask_other, + "no_mask_overlap": cfg.no_mask_overlap, + "mask_channel_length": cfg.mask_channel_length, + "mask_channel_prob": cfg.mask_channel_prob, + "mask_channel_before": cfg.mask_channel_before, + "mask_channel_selection": cfg.mask_channel_selection, + "mask_channel_other": cfg.mask_channel_other, + "no_mask_channel_overlap": cfg.no_mask_channel_overlap, + "encoder_layerdrop": cfg.layerdrop, + "feature_grad_mult": cfg.feature_grad_mult, + "checkpoint_activations": cfg.checkpoint_activations, + "offload_activations": cfg.offload_activations, + "min_params_to_wrap": cfg.min_params_to_wrap, + } + + if cfg.w2v_args is None: + state = checkpoint_utils.load_checkpoint_to_cpu(cfg.w2v_path, arg_overrides) + w2v_args = state.get("cfg", None) + if w2v_args is None: + w2v_args = convert_namespace_to_omegaconf(state["args"]) + w2v_args.criterion = None + w2v_args.lr_scheduler = None + cfg.w2v_args = w2v_args + + logger.info(w2v_args) + + else: + state = None + w2v_args = cfg.w2v_args + if isinstance(w2v_args, Namespace): + cfg.w2v_args = w2v_args = convert_namespace_to_omegaconf(w2v_args) + + model_normalized = w2v_args.task.get( + "normalize", w2v_args.model.get("normalize", False) + ) + assert cfg.normalize == model_normalized, ( + "Fine-tuning works best when data normalization is the same. " + "Please check that --normalize is set or unset for both pre-training and here" + ) + + if hasattr(cfg, "checkpoint_activations") and cfg.checkpoint_activations: + with open_dict(w2v_args): + w2v_args.model.checkpoint_activations = cfg.checkpoint_activations + + w2v_args.task.data = cfg.data + task = tasks.setup_task(w2v_args.task) + model = task.build_model(w2v_args.model, from_checkpoint=True) + + model.remove_pretraining_modules() + + if state is not None and not cfg.no_pretrained_weights: + self.load_model_weights(state, model, cfg) + + super().__init__(task.source_dictionary) + + d = w2v_args.model.encoder_embed_dim + + self.w2v_model = model + + self.final_dropout = nn.Dropout(cfg.final_dropout) + self.freeze_finetune_updates = cfg.freeze_finetune_updates + self.num_updates = 0 + + targ_d = None + self.proj = None + + if output_size is not None: + targ_d = output_size + elif getattr(cfg, "decoder_embed_dim", d) != d: + targ_d = cfg.decoder_embed_dim + + if targ_d is not None: + self.proj = Linear(d, targ_d) + + def load_model_weights(self, state, model, cfg): + if cfg.ddp_backend == "fully_sharded": + from fairseq.distributed import FullyShardedDataParallel + + for name, module in model.named_modules(): + if "encoder.layers" in name and len(name.split(".")) == 3: + # Only for layers, we do a special handling and load the weights one by one + # We dont load all weights together as that wont be memory efficient and may + # cause oom + new_dict = { + k.replace(name + ".", ""): v + for (k, v) in state["model"].items() + if name + "." in k + } + assert isinstance(module, FullyShardedDataParallel) + with module.summon_full_params(): + module.load_state_dict(new_dict, strict=True) + module._reset_lazy_init() + + # Once layers are loaded, filter them out and load everything else. + r = re.compile("encoder.layers.\d.") + filtered_list = list(filter(r.match, state["model"].keys())) + + new_big_dict = { + k: v for (k, v) in state["model"].items() if k not in filtered_list + } + + model.load_state_dict(new_big_dict, strict=False) + else: + if "_ema" in state["model"]: + del state["model"]["_ema"] + model.load_state_dict(state["model"], strict=True) + + def set_num_updates(self, num_updates): + """Set the number of parameters updates.""" + super().set_num_updates(num_updates) + self.num_updates = num_updates + + def forward(self, source, padding_mask, **kwargs): + + w2v_args = { + "source": source, + "padding_mask": padding_mask, + "mask": self.apply_mask and self.training, + } + + ft = self.freeze_finetune_updates <= self.num_updates + + with torch.no_grad() if not ft else contextlib.ExitStack(): + res = self.w2v_model.extract_features(**w2v_args) + + x = res["x"] + padding_mask = res["padding_mask"] + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + x = self.final_dropout(x) + + if self.proj: + x = self.proj(x) + + return { + "encoder_out": x, # T x B x C + "padding_mask": padding_mask, # B x T, + "layer_results": res["layer_results"], + } + + def forward_torchscript(self, net_input): + if torch.jit.is_scripting(): + return self.forward(net_input["source"], net_input["padding_mask"]) + else: + return self.forward_non_torchscript(net_input) + + def reorder_encoder_out(self, encoder_out, new_order): + if encoder_out["encoder_out"] is not None: + encoder_out["encoder_out"] = encoder_out["encoder_out"].index_select( + 1, new_order + ) + if encoder_out["padding_mask"] is not None: + encoder_out["padding_mask"] = encoder_out["padding_mask"].index_select( + 0, new_order + ) + return encoder_out + + def max_positions(self): + """Maximum input length supported by the encoder.""" + return None + + def upgrade_state_dict_named(self, state_dict, name): + return state_dict + + +class TransformerDecoder(FairseqIncrementalDecoder): + """ + Transformer decoder consisting of *args.decoder_layers* layers. Each layer + is a :class:`TransformerDecoderLayer`. + + Args: + args (argparse.Namespace): parsed command-line arguments + dictionary (~fairseq.data.Dictionary): decoding dictionary + embed_tokens (torch.nn.Embedding): output embedding + no_encoder_attn (bool, optional): whether to attend to encoder outputs + (default: False). + """ + + def __init__( + self, + cfg: Wav2Vec2Seq2SeqConfig, + dictionary, + embed_tokens, + no_encoder_attn=False, + ): + super().__init__(dictionary) + + self.dropout = cfg.decoder_dropout + self.share_input_output_embed = cfg.share_decoder_input_output_embed + + input_embed_dim = embed_tokens.embedding_dim + embed_dim = cfg.decoder_embed_dim + self.output_embed_dim = cfg.decoder_embed_dim + + self.layerdrop = cfg.decoder_layerdrop + + self.padding_idx = embed_tokens.padding_idx + self.max_target_positions = cfg.max_target_positions + + self.embed_tokens = embed_tokens + self.embed_scale = math.sqrt(embed_dim) # todo: try with input_embed_dim + + self.project_in_dim = ( + Linear(input_embed_dim, embed_dim, bias=False) + if embed_dim != input_embed_dim + else None + ) + + self.embed_positions = ( + PositionalEmbedding( + cfg.max_target_positions, + embed_dim, + self.padding_idx, + learned=cfg.decoder_learned_pos, + ) + if not cfg.no_token_positional_embeddings + else None + ) + + # TODO: update this when transformer gets converted to dataclass configs + transformer_cfg = copy.deepcopy(cfg) + with open_dict(transformer_cfg): + transformer_cfg.dropout = transformer_cfg.decoder_dropout + transformer_cfg.attention_dropout = ( + transformer_cfg.decoder_attention_dropout + ) + transformer_cfg.activation_dropout = ( + transformer_cfg.decoder_activation_dropout + ) + + self.layers = nn.ModuleList([]) + self.layers.extend( + [ + TransformerDecoderLayer(transformer_cfg, no_encoder_attn) + for _ in range(transformer_cfg.decoder_layers) + ] + ) + + if not self.share_input_output_embed: + self.embed_out = nn.Parameter( + torch.Tensor(len(dictionary), self.output_embed_dim) + ) + nn.init.normal_(self.embed_out, mean=0, std=self.output_embed_dim**-0.5) + + if transformer_cfg.decoder_normalize_before: + self.layer_norm = LayerNorm(embed_dim) + else: + self.layer_norm = None + + def forward( + self, prev_output_tokens, encoder_out=None, incremental_state=None, **unused + ): + """ + Args: + prev_output_tokens (LongTensor): previous decoder outputs of shape + `(batch, tgt_len)`, for teacher forcing + encoder_out (Tensor, optional): output from the encoder, used for + encoder-side attention + incremental_state (dict): dictionary used for storing state during + :ref:`Incremental decoding` + + Returns: + tuple: + - the decoder's output of shape `(batch, tgt_len, vocab)` + - a dictionary with any model-specific outputs + """ + prev_output_tokens = prev_output_tokens.long() + x, extra = self.extract_features( + prev_output_tokens, encoder_out, incremental_state + ) + x = self.output_layer(x) + return x, extra + + def extract_features( + self, prev_output_tokens, encoder_out=None, incremental_state=None, **unused + ): + """ + Similar to *forward* but only return features. + + Returns: + tuple: + - the decoder's features of shape `(batch, tgt_len, embed_dim)` + - a dictionary with any model-specific outputs + """ + + # embed positions + positions = ( + self.embed_positions( + prev_output_tokens, incremental_state=incremental_state + ) + if self.embed_positions is not None + else None + ) + + if incremental_state is not None: + prev_output_tokens = prev_output_tokens[:, -1:] + if positions is not None: + positions = positions[:, -1:] + + # embed tokens and positions + x = self.embed_scale * self.embed_tokens(prev_output_tokens) + + if self.project_in_dim is not None: + x = self.project_in_dim(x) + + if positions is not None: + x += positions + x = F.dropout(x, p=self.dropout, training=self.training) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + attn = None + + inner_states = [x] + + # decoder layers + self_attn_padding_mask = None + if prev_output_tokens.eq(self.padding_idx).any(): + self_attn_padding_mask = prev_output_tokens.eq(self.padding_idx) + for layer in self.layers: + dropout_probability = np.random.random() + if not self.training or (dropout_probability > self.layerdrop): + x, attn, _ = layer( + x, + encoder_out["encoder_out"] if encoder_out is not None else None, + encoder_out["padding_mask"] if encoder_out is not None else None, + incremental_state, + self_attn_mask=self.buffered_future_mask(x) + if incremental_state is None + else None, + self_attn_padding_mask=self_attn_padding_mask, + ) + inner_states.append(x) + + if self.layer_norm: + x = self.layer_norm(x) + + # T x B x C -> B x T x C + x = x.transpose(0, 1) + + return x, {"attn": attn, "inner_states": inner_states} + + def output_layer(self, features, **kwargs): + """Project features to the vocabulary size.""" + # project back to size of vocabulary + if self.share_input_output_embed: + return F.linear(features, self.embed_tokens.weight) + else: + return F.linear(features, self.embed_out) + + def max_positions(self): + """Maximum output length supported by the decoder.""" + if self.embed_positions is None: + return self.max_target_positions + return min(self.max_target_positions, self.embed_positions.max_positions) + + def buffered_future_mask(self, tensor): + dim = tensor.size(0) + if ( + not hasattr(self, "_future_mask") + or self._future_mask is None + or self._future_mask.device != tensor.device + or self._future_mask.size(0) < dim + ): + self._future_mask = torch.triu( + utils.fill_with_neg_inf(tensor.new(dim, dim)), 1 + ) + return self._future_mask[:dim, :dim] + + def upgrade_state_dict_named(self, state_dict, name): + return state_dict + + +def Embedding(num_embeddings, embedding_dim, padding_idx): + m = nn.Embedding(num_embeddings, embedding_dim, padding_idx=padding_idx) + nn.init.normal_(m.weight, mean=0, std=embedding_dim**-0.5) + nn.init.constant_(m.weight[padding_idx], 0) + return m + + +def Linear(in_features, out_features, bias=True): + m = nn.Linear(in_features, out_features, bias) + nn.init.xavier_uniform_(m.weight) + if bias: + nn.init.constant_(m.bias, 0.0) + return m diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/xmod/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/models/xmod/__init__.py new file mode 100644 index 00000000..bbf76949 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/xmod/__init__.py @@ -0,0 +1,7 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .model import * # noqa +from .transformer_layer_xmod import * # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/xmod/hub_interface.py b/PyTorch/NLP/new-Transformer/fairseq/models/xmod/hub_interface.py new file mode 100644 index 00000000..909bb423 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/xmod/hub_interface.py @@ -0,0 +1,51 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from fairseq.models.roberta.hub_interface import RobertaHubInterface +import torch +import torch.nn.functional as F + + +class XMODHubInterface(RobertaHubInterface): + def extract_features( + self, + tokens: torch.LongTensor, + return_all_hiddens: bool = False, + lang_id=None, + ) -> torch.Tensor: + if tokens.dim() == 1: + tokens = tokens.unsqueeze(0) + if tokens.size(-1) > self.model.max_positions(): + raise ValueError( + "tokens exceeds maximum length: {} > {}".format( + tokens.size(-1), self.model.max_positions() + ) + ) + features, extra = self.model( + tokens.to(device=self.device), + features_only=True, + return_all_hiddens=return_all_hiddens, + lang_id=lang_id, + ) + if return_all_hiddens: + # convert from T x B x C -> B x T x C + inner_states = extra["inner_states"] + return [inner_state.transpose(0, 1) for inner_state in inner_states] + else: + return features # just the last layer's features + + def predict( + self, + head: str, + tokens: torch.LongTensor, + return_logits: bool = False, + lang_id=None, + ): + features = self.extract_features(tokens.to(device=self.device), lang_id=lang_id) + logits = self.model.classification_heads[head](features) + if return_logits: + return logits + return F.log_softmax(logits, dim=-1) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/xmod/model.py b/PyTorch/NLP/new-Transformer/fairseq/models/xmod/model.py new file mode 100644 index 00000000..fb6c7a8d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/xmod/model.py @@ -0,0 +1,742 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from ..roberta.model_xlmr import XLMRModel +from fairseq.models.xmod.transformer_layer_xmod import XMODTransformerEncoderLayerBase +from ..roberta.model import base_architecture, RobertaEncoder +from fairseq.models.transformer import TransformerEncoder +from fairseq.modules.transformer_sentence_encoder import init_bert_params +from typing import Optional +from fairseq.models.xmod.hub_interface import XMODHubInterface +import torch +from fairseq.distributed import fsdp_wrap +from fairseq.models import ( + register_model, + register_model_architecture, +) + +from fairseq.modules.checkpoint_activations import checkpoint_wrapper + +DEFAULT_MIN_PARAMS_TO_WRAP = int(1e8) + + +@register_model("xmod") +class XMODModel(XLMRModel): + @classmethod + def hub_models(cls): + return { + "xmod.base": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.base.81.1M.tar.gz", + "xmod.large.prenorm": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.large.prenorm.81.500k.tar.gz", + "xmod.base.13.125k": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.base.13.125k.tar.gz", + "xmod.base.30.125k": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.base.30.125k.tar.gz", + "xmod.base.30.195k": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.base.30.195k.tar.gz", + "xmod.base.60.125k": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.base.60.125k.tar.gz", + "xmod.base.60.265k": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.base.60.265k.tar.gz", + "xmod.base.75.125k": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.base.75.125k.tar.gz", + "xmod.base.75.269k": "https://dl.fbaipublicfiles.com/fairseq/models/xmod/xmod.base.75.269k.tar.gz", + } + + @classmethod + def from_pretrained( + cls, + model_name_or_path, + checkpoint_file="model.pt", + data_name_or_path=".", + bpe="sentencepiece", + **kwargs, + ): + from fairseq import hub_utils + + x = hub_utils.from_pretrained( + model_name_or_path, + checkpoint_file, + data_name_or_path, + archive_map=cls.hub_models(), + bpe=bpe, + load_checkpoint_heads=True, + **kwargs, + ) + return XMODHubInterface(x["args"], x["task"], x["models"][0]) + + @classmethod + def build_model(cls, args, task): + """Build a new model instance.""" + + from omegaconf import OmegaConf + + if OmegaConf.is_config(args): + OmegaConf.set_struct(args, False) + + # make sure all arguments are present + base_architecture(args) + + if not hasattr(args, "max_positions"): + if not hasattr(args, "tokens_per_sample"): + args.tokens_per_sample = task.max_positions() + args.max_positions = args.tokens_per_sample + + encoder = XMODEncoder(args, task.source_dictionary) + + if OmegaConf.is_config(args): + OmegaConf.set_struct(args, True) + + return cls(args, encoder) + + def forward( + self, + src_tokens, + features_only=False, + return_all_hiddens=False, + classification_head_name=None, + lang_id=None, + **kwargs, + ): + if classification_head_name is not None: + features_only = True + x, extra = self.encoder( + src_tokens, features_only, return_all_hiddens, lang_id=lang_id, **kwargs + ) + + if classification_head_name is not None: + x = self.classification_heads[classification_head_name](x) + return x, extra + + +class XMODEncoder(RobertaEncoder): + """XMOD encoder.""" + + def build_encoder(self, args, dictionary, embed_tokens): + encoder = XMODTransformerEncoder(args, dictionary, embed_tokens) + encoder.apply(init_bert_params) + return encoder + + def forward( + self, + src_tokens, + features_only=False, + return_all_hiddens=False, + masked_tokens=None, + lang_id=None, + **unused, + ): + """ + Args: + src_tokens (LongTensor): input tokens of shape `(batch, src_len)` + features_only (bool, optional): skip LM head and just return + features. If True, the output will be of shape + `(batch, src_len, embed_dim)`. + return_all_hiddens (bool, optional): also return all of the + intermediate hidden states (default: False). + + Returns: + tuple: + - the LM output of shape `(batch, src_len, vocab)` + - a dictionary of additional data, where 'inner_states' + is a list of hidden states. Note that the hidden + states have shape `(src_len, batch, vocab)`. + """ + x, extra = self.extract_features( + src_tokens, return_all_hiddens=return_all_hiddens, lang_id=lang_id + ) + if not features_only: + x = self.output_layer(x, masked_tokens=masked_tokens) + return x, extra + + def extract_features( + self, src_tokens, return_all_hiddens=False, lang_id=None, **kwargs + ): + encoder_out = self.sentence_encoder( + src_tokens, + return_all_hiddens=return_all_hiddens, + lang_id=lang_id, + token_embeddings=kwargs.get("token_embeddings", None), + ) + # T x B x C -> B x T x C + features = encoder_out["encoder_out"][0].transpose(0, 1) + inner_states = encoder_out["encoder_states"] if return_all_hiddens else None + return features, {"inner_states": inner_states} + + +class XMODTransformerEncoder(TransformerEncoder): + def build_encoder_layer(self, cfg): + layer = XMODTransformerEncoderLayerBase(cfg) + checkpoint = cfg.checkpoint_activations + if checkpoint: + offload_to_cpu = cfg.offload_activations + layer = checkpoint_wrapper(layer, offload_to_cpu=offload_to_cpu) + # if we are checkpointing, enforce that FSDP always wraps the + # checkpointed layer, regardless of layer size + min_params_to_wrap = cfg.min_params_to_wrap if not checkpoint else 0 + layer = fsdp_wrap(layer, min_num_params=min_params_to_wrap) + return layer + + def forward( + self, + src_tokens, + src_lengths: Optional[torch.Tensor] = None, + return_all_hiddens: bool = False, + token_embeddings: Optional[torch.Tensor] = None, + lang_id=None, + ): + """ + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (torch.LongTensor): lengths of each source sentence of + shape `(batch)` + return_all_hiddens (bool, optional): also return all of the + intermediate hidden states (default: False). + token_embeddings (torch.Tensor, optional): precomputed embeddings + default `None` will recompute embeddings + + Returns: + dict: + - **encoder_out** (Tensor): the last encoder layer's output of + shape `(src_len, batch, embed_dim)` + - **encoder_padding_mask** (ByteTensor): the positions of + padding elements of shape `(batch, src_len)` + - **encoder_embedding** (Tensor): the (scaled) embedding lookup + of shape `(batch, src_len, embed_dim)` + - **encoder_states** (List[Tensor]): all intermediate + hidden states of shape `(src_len, batch, embed_dim)`. + Only populated if *return_all_hiddens* is True. + """ + return self.forward_scriptable( + src_tokens, + src_lengths, + return_all_hiddens, + token_embeddings, + lang_id=lang_id, + ) + # TorchScript doesn't support super() method so that the scriptable Subclass + # can't access the base class model in Torchscript. + # Current workaround is to add a helper function with different name and + # call the helper function from scriptable Subclass. + + def forward_scriptable( + self, + src_tokens, + src_lengths: Optional[torch.Tensor] = None, + return_all_hiddens: bool = False, + token_embeddings: Optional[torch.Tensor] = None, + lang_id=None, + ): + """ + Args: + src_tokens (LongTensor): tokens in the source language of shape + `(batch, src_len)` + src_lengths (torch.LongTensor): lengths of each source sentence of + shape `(batch)` + return_all_hiddens (bool, optional): also return all of the + intermediate hidden states (default: False). + token_embeddings (torch.Tensor, optional): precomputed embeddings + default `None` will recompute embeddings + + Returns: + dict: + - **encoder_out** (Tensor): the last encoder layer's output of + shape `(src_len, batch, embed_dim)` + - **encoder_padding_mask** (ByteTensor): the positions of + padding elements of shape `(batch, src_len)` + - **encoder_embedding** (Tensor): the (scaled) embedding lookup + of shape `(batch, src_len, embed_dim)` + - **encoder_states** (List[Tensor]): all intermediate + hidden states of shape `(src_len, batch, embed_dim)`. + Only populated if *return_all_hiddens* is True. + """ + # compute padding mask + encoder_padding_mask = src_tokens.eq(self.padding_idx) + has_pads = src_tokens.device.type == "xla" or encoder_padding_mask.any() + + x, encoder_embedding = self.forward_embedding(src_tokens, token_embeddings) + + # account for padding while computing the representation + if has_pads: + x = x * (1 - encoder_padding_mask.unsqueeze(-1).type_as(x)) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + encoder_states = [] + + if return_all_hiddens: + encoder_states.append(x) + + # encoder layers + for layer in self.layers: + x = layer( + x, + encoder_padding_mask=encoder_padding_mask if has_pads else None, + lang_id=lang_id, + ) + if return_all_hiddens: + assert encoder_states is not None + encoder_states.append(x) + + if self.layer_norm is not None: + x = self.layer_norm(x) + + # The Pytorch Mobile lite interpreter does not supports returning NamedTuple in + # `forward` so we use a dictionary instead. + # TorchScript does not support mixed values so the values are all lists. + # The empty list is equivalent to None. + src_lengths = ( + src_tokens.ne(self.padding_idx) + .sum(dim=1, dtype=torch.int32) + .reshape(-1, 1) + .contiguous() + ) + return { + "encoder_out": [x], # T x B x C + "encoder_padding_mask": [encoder_padding_mask], # B x T + "encoder_embedding": [encoder_embedding], # B x T x C + "encoder_states": encoder_states, # List[T x B x C] + "src_tokens": [], + "src_lengths": [src_lengths], + } + + +@register_model_architecture("xmod", "xmod_base_13") +def roberta_base_architecture(args): + args.ffn_modules = getattr(args, "ffn_modules", False) + args.adapter_modules = getattr(args, "adapter_modules", True) + args.adapter_layer_norm = getattr(args, "adapter_layer_norm", False) + args.adapter_reuse_layer_norm = getattr(args, "adapter_reuse_layer_norm", True) + args.ln_before_adapter = getattr(args, "ln_before_adapter", True) + args.languages = getattr( + args, + "languages", + [ + "ar_AR", + "en_XX", + "fi_FI", + "fr_XX", + "hi_IN", + "id_ID", + "ka_GE", + "ko_KR", + "ru_RU", + "sw_KE", + "ta_IN", + "th_TH", + "vi_VN", + ], + ) + base_architecture(args) + + +@register_model_architecture("xmod", "xmod_base_30") +def roberta_base_architecture(args): + args.ffn_modules = getattr(args, "ffn_modules", False) + args.adapter_modules = getattr(args, "adapter_modules", True) + args.adapter_layer_norm = getattr(args, "adapter_layer_norm", False) + args.adapter_reuse_layer_norm = getattr(args, "adapter_reuse_layer_norm", True) + args.ln_before_adapter = getattr(args, "ln_before_adapter", True) + args.languages = getattr( + args, + "languages", + [ + "ar_AR", + "cs_CZ", + "en_XX", + "eu_ES", + "fi_FI", + "fr_XX", + "hi_IN", + "hr_HR", + "hu_HU", + "hy_AM", + "id_ID", + "it_IT", + "ka_GE", + "ko_KR", + "lt_LT", + "ml_IN", + "mn_MN", + "ms_MY", + "pl_PL", + "ro_RO", + "ru_RU", + "si_LK", + "sk_SK", + "sq_AL", + "sv_SE", + "sw_KE", + "ta_IN", + "th_TH", + "tl_XX", + "vi_VN", + ], + ) + base_architecture(args) + + +@register_model_architecture("xmod", "xmod_base_60") +def roberta_base_architecture(args): + args.ffn_modules = getattr(args, "ffn_modules", False) + args.adapter_modules = getattr(args, "adapter_modules", True) + args.adapter_layer_norm = getattr(args, "adapter_layer_norm", False) + args.adapter_reuse_layer_norm = getattr(args, "adapter_reuse_layer_norm", True) + args.ln_before_adapter = getattr(args, "ln_before_adapter", True) + args.languages = getattr( + args, + "languages", + [ + "af_ZA", + "am_ET", + "ar_AR", + "be_BY", + "bn_IN", + "ca_ES", + "cs_CZ", + "cy_GB", + "da_DK", + "en_XX", + "eo_EO", + "et_EE", + "eu_ES", + "fa_IR", + "fi_FI", + "fr_XX", + "ga_IE", + "gl_ES", + "gu_IN", + "ha_NG", + "hi_IN", + "hr_HR", + "hu_HU", + "hy_AM", + "id_ID", + "is_IS", + "it_IT", + "ka_GE", + "ko_KR", + "ku_TR", + "la_VA", + "lt_LT", + "lv_LV", + "mk_MK", + "ml_IN", + "mn_MN", + "ms_MY", + "ne_NP", + "nl_XX", + "no_XX", + "pl_PL", + "ps_AF", + "pt_XX", + "ro_RO", + "ru_RU", + "sa_IN", + "sd_PK", + "si_LK", + "sk_SK", + "sl_SI", + "so_SO", + "sq_AL", + "sr_RS", + "sv_SE", + "sw_KE", + "ta_IN", + "te_IN", + "th_TH", + "tl_XX", + "vi_VN", + ], + ) + base_architecture(args) + + +@register_model_architecture("xmod", "xmod_base_75") +def roberta_base_architecture(args): + args.ffn_modules = getattr(args, "ffn_modules", False) + args.adapter_modules = getattr(args, "adapter_modules", True) + args.adapter_layer_norm = getattr(args, "adapter_layer_norm", False) + args.adapter_reuse_layer_norm = getattr(args, "adapter_reuse_layer_norm", True) + args.ln_before_adapter = getattr(args, "ln_before_adapter", True) + args.languages = getattr( + args, + "languages", + [ + "af_ZA", + "am_ET", + "ar_AR", + "as_IN", + "be_BY", + "bn_IN", + "br_FR", + "bs_BA", + "ca_ES", + "cs_CZ", + "cy_GB", + "da_DK", + "en_XX", + "eo_EO", + "et_EE", + "eu_ES", + "fa_IR", + "fi_FI", + "fr_XX", + "fy_NL", + "ga_IE", + "gd_GB", + "gl_ES", + "gu_IN", + "ha_NG", + "hi_IN", + "hr_HR", + "hu_HU", + "hy_AM", + "id_ID", + "is_IS", + "it_IT", + "jv_ID", + "ka_GE", + "kn_IN", + "ko_KR", + "ku_TR", + "la_VA", + "lt_LT", + "lv_LV", + "mg_MG", + "mk_MK", + "ml_IN", + "mn_MN", + "mr_IN", + "ms_MY", + "ne_NP", + "nl_XX", + "no_XX", + "om_KE", + "or_IN", + "pa_IN", + "pl_PL", + "ps_AF", + "pt_XX", + "ro_RO", + "ru_RU", + "sa_IN", + "sd_PK", + "si_LK", + "sk_SK", + "sl_SI", + "so_SO", + "sq_AL", + "sr_RS", + "su_ID", + "sv_SE", + "sw_KE", + "ta_IN", + "te_IN", + "th_TH", + "tl_XX", + "vi_VN", + "xh_ZA", + "yi_DE", + ], + ) + base_architecture(args) + + +@register_model_architecture("xmod", "xmod_base") +def roberta_base_architecture(args): + args.ffn_modules = getattr(args, "ffn_modules", False) + args.adapter_modules = getattr(args, "adapter_modules", True) + args.adapter_layer_norm = getattr(args, "adapter_layer_norm", False) + args.adapter_reuse_layer_norm = getattr(args, "adapter_reuse_layer_norm", True) + args.ln_before_adapter = getattr(args, "ln_before_adapter", True) + args.languages = getattr( + args, + "languages", + [ + "en_XX", + "id_ID", + "vi_VN", + "ru_RU", + "fa_IR", + "sv_SE", + "ja_XX", + "fr_XX", + "de_DE", + "ro_RO", + "ko_KR", + "hu_HU", + "es_XX", + "fi_FI", + "uk_UA", + "da_DK", + "pt_XX", + "no_XX", + "th_TH", + "pl_PL", + "bg_BG", + "nl_XX", + "zh_CN", + "he_IL", + "el_GR", + "it_IT", + "sk_SK", + "hr_HR", + "tr_TR", + "ar_AR", + "cs_CZ", + "lt_LT", + "hi_IN", + "zh_TW", + "ca_ES", + "ms_MY", + "sl_SI", + "lv_LV", + "ta_IN", + "bn_IN", + "et_EE", + "az_AZ", + "sq_AL", + "sr_RS", + "kk_KZ", + "ka_GE", + "tl_XX", + "ur_PK", + "is_IS", + "hy_AM", + "ml_IN", + "mk_MK", + "be_BY", + "la_VA", + "te_IN", + "eu_ES", + "gl_ES", + "mn_MN", + "kn_IN", + "ne_NP", + "sw_KE", + "si_LK", + "mr_IN", + "af_ZA", + "gu_IN", + "cy_GB", + "eo_EO", + "km_KH", + "ky_KG", + "uz_UZ", + "ps_AF", + "pa_IN", + "ga_IE", + "ha_NG", + "am_ET", + "lo_LA", + "ku_TR", + "so_SO", + "my_MM", + "or_IN", + "sa_IN", + ], + ) + base_architecture(args) + + +@register_model_architecture("xmod", "xmod_large_prenorm") +def roberta_base_architecture(args): + args.ffn_modules = getattr(args, "ffn_modules", False) + args.adapter_modules = getattr(args, "adapter_modules", True) + args.adapter_layer_norm = getattr(args, "adapter_layer_norm", True) + args.adapter_reuse_layer_norm = getattr(args, "adapter_reuse_layer_norm", False) + args.ln_before_adapter = getattr(args, "ln_before_adapter", False) + # args.bottleneck = getattr(args, "bottleneck", 8) + args.bottleneck = getattr(args, "bottleneck", 4) + args.languages = getattr( + args, + "languages", + [ + "en_XX", + "id_ID", + "vi_VN", + "ru_RU", + "fa_IR", + "sv_SE", + "ja_XX", + "fr_XX", + "de_DE", + "ro_RO", + "ko_KR", + "hu_HU", + "es_XX", + "fi_FI", + "uk_UA", + "da_DK", + "pt_XX", + "no_XX", + "th_TH", + "pl_PL", + "bg_BG", + "nl_XX", + "zh_CN", + "he_IL", + "el_GR", + "it_IT", + "sk_SK", + "hr_HR", + "tr_TR", + "ar_AR", + "cs_CZ", + "lt_LT", + "hi_IN", + "zh_TW", + "ca_ES", + "ms_MY", + "sl_SI", + "lv_LV", + "ta_IN", + "bn_IN", + "et_EE", + "az_AZ", + "sq_AL", + "sr_RS", + "kk_KZ", + "ka_GE", + "tl_XX", + "ur_PK", + "is_IS", + "hy_AM", + "ml_IN", + "mk_MK", + "be_BY", + "la_VA", + "te_IN", + "eu_ES", + "gl_ES", + "mn_MN", + "kn_IN", + "ne_NP", + "sw_KE", + "si_LK", + "mr_IN", + "af_ZA", + "gu_IN", + "cy_GB", + "eo_EO", + "km_KH", + "ky_KG", + "uz_UZ", + "ps_AF", + "pa_IN", + "ga_IE", + "ha_NG", + "am_ET", + "lo_LA", + "ku_TR", + "so_SO", + "my_MM", + "or_IN", + "sa_IN", + ], + ) + + args.encoder_normalize_before = getattr(args, "encoder_normalize_before", True) + args.encoder_layers = getattr(args, "encoder_layers", 24) + args.encoder_embed_dim = getattr(args, "encoder_embed_dim", 1024) + args.encoder_ffn_embed_dim = getattr(args, "encoder_ffn_embed_dim", 4096) + args.encoder_attention_heads = getattr(args, "encoder_attention_heads", 16) + base_architecture(args) diff --git a/PyTorch/NLP/new-Transformer/fairseq/models/xmod/transformer_layer_xmod.py b/PyTorch/NLP/new-Transformer/fairseq/models/xmod/transformer_layer_xmod.py new file mode 100644 index 00000000..47a91cdc --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/models/xmod/transformer_layer_xmod.py @@ -0,0 +1,179 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.modules.transformer_layer import TransformerEncoderLayer +from typing import Optional +import torch +import torch.nn as nn +from fairseq import utils +from fairseq.modules import LayerNorm +from fairseq.modules.fairseq_dropout import FairseqDropout +from fairseq.modules.quant_noise import quant_noise +from torch import Tensor + + +class Adapter(nn.Module): + def __init__(self, cfg, red_fac=2): + super(Adapter, self).__init__() + self.cfg = cfg + self.embed_dim = cfg.encoder_embed_dim + self.quant_noise = getattr(cfg, "quant_noise_pq", 0) + self.quant_noise_block_size = getattr(cfg, "quant_noise_pq_block_size", 8) or 8 + self.activation_fn = utils.get_activation_fn( + activation=getattr(cfg, "activation_fn", "relu") or "relu" + ) + self.fc1 = quant_noise( + nn.Linear(self.embed_dim, self.embed_dim // red_fac), + p=self.quant_noise, + block_size=self.quant_noise_block_size, + ) + self.fc2 = quant_noise( + nn.Linear(self.embed_dim // red_fac, self.embed_dim), + p=self.quant_noise, + block_size=self.quant_noise_block_size, + ) + activation_dropout_p = getattr(cfg, "activation_dropout", 0) or 0 + if activation_dropout_p == 0: + # for backwards compatibility with models that use cfg.relu_dropout + activation_dropout_p = getattr(cfg, "relu_dropout", 0) or 0 + self.activation_dropout_module = FairseqDropout( + float(activation_dropout_p), module_name=self.__class__.__name__ + ) + + def forward(self, x): + x = self.activation_fn(self.fc1(x)) + if not hasattr(self.cfg, "adapter_dropout") or self.cfg.adapter_dropout: + x = self.activation_dropout_module(x) + x = self.fc2(x) + return x + + +class XMODTransformerEncoderLayerBase(TransformerEncoderLayer): + """Encoder layer block. + + In the original paper each operation (multi-head attention or FFN) is + postprocessed with: `dropout -> add residual -> layernorm`. In the + tensor2tensor code they suggest that learning is more robust when + preprocessing each layer with layernorm and postprocessing with: + `dropout -> add residual`. We default to the approach in the paper, but the + tensor2tensor approach can be enabled by setting + *cfg.encoder.normalize_before* to ``True``. + + Args: + args (argparse.Namespace): parsed command-line arguments + """ + + def __init__(self, cfg): + super().__init__(cfg) + if hasattr(cfg, "adapter_modules") and cfg.adapter_modules: + export = getattr(cfg, "export", False) + if cfg.adapter_layer_norm: + self.adapter_layer_norm = LayerNorm(self.embed_dim, export=export) + self.adapter_modules = nn.ModuleDict(dict()) + if hasattr(self.cfg, "bottleneck"): + bottleneck = self.cfg.bottleneck + else: + bottleneck = 2 + for language in cfg.languages: + self.adapter_modules[str(language)] = Adapter(cfg, red_fac=bottleneck) + + def lang_adapter(self, lang_id, x): + # If language adapters exist pass throught them + if hasattr(self.cfg, "adapter_modules") and self.cfg.adapter_modules: + if lang_id is None: + lang_id = ["en_XX"] * x.shape[1] + d_langs = [lang_id[0]] + lang_lengths = [1] + for lang in lang_id[1:]: + if lang == d_langs[-1]: + lang_lengths[-1] += 1 + else: + d_langs.append(lang) + lang_lengths.append(1) + + if ( + not hasattr(self.cfg, "ln_before_adapter") + or not self.cfg.ln_before_adapter + ): + residual = x + if self.cfg.adapter_layer_norm: + x = self.adapter_layer_norm(x) + elif self.cfg.adapter_reuse_layer_norm: + x = self.final_layer_norm(x) + if hasattr(self.cfg, "ln_before_adapter") and self.cfg.ln_before_adapter: + residual = x + + split_x = torch.split(x, lang_lengths, 1) + x_ = [] + for i, (lang, s_x) in enumerate(zip(d_langs, split_x)): + lang = lang.replace("_rom", "").replace("_zaw", "") + x_.append(self.adapter_modules[str(lang)](s_x)) + x = torch.cat(x_, 1) + + x = self.dropout_module(x) + x = self.residual_connection(x, residual) + + return x + + def forward( + self, + x, + encoder_padding_mask: Optional[Tensor], + attn_mask: Optional[Tensor] = None, + lang_id: Optional[list] = None, + ): + """ + Args: + x (Tensor): input to the layer of shape `(seq_len, batch, embed_dim)` + encoder_padding_mask (ByteTensor): binary ByteTensor of shape + `(batch, seq_len)` where padding elements are indicated by ``1``. + attn_mask (ByteTensor): binary tensor of shape `(tgt_len, src_len)`, + where `tgt_len` is the length of output and `src_len` is the + length of input, though here both are equal to `seq_len`. + `attn_mask[tgt_i, src_j] = 1` means that when calculating the + embedding for `tgt_i`, we exclude (mask out) `src_j`. This is + useful for strided self-attention. + + Returns: + encoded output of shape `(seq_len, batch, embed_dim)` + """ + # anything in original attn_mask = 1, becomes -1e8 + # anything in original attn_mask = 0, becomes 0 + # Note that we cannot use -inf here, because at some edge cases, + # the attention weight (before softmax) for some padded element in query + # will become -inf, which results in NaN in model parameters + if attn_mask is not None: + attn_mask = attn_mask.masked_fill(attn_mask.to(torch.bool), -1e8) + + residual = x + if self.normalize_before: + x = self.self_attn_layer_norm(x) + x, _ = self.self_attn( + query=x, + key=x, + value=x, + key_padding_mask=encoder_padding_mask, + need_weights=False, + attn_mask=attn_mask, + ) + x = self.dropout_module(x) + x = self.residual_connection(x, residual) + if not self.normalize_before: + x = self.self_attn_layer_norm(x) + + residual = x + if self.normalize_before: + x = self.final_layer_norm(x) + x = self.activation_fn(self.fc1(x)) + x = self.activation_dropout_module(x) + x = self.fc2(x) + x = self.dropout_module(x) + x = self.residual_connection(x, residual) + + x = self.lang_adapter(lang_id, x) + + if not self.normalize_before: + x = self.final_layer_norm(x) + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/modules/__init__.py new file mode 100644 index 00000000..8ad7f647 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/__init__.py @@ -0,0 +1,104 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +from .adaptive_input import AdaptiveInput +from .adaptive_softmax import AdaptiveSoftmax +from .base_layer import BaseLayer +from .beamable_mm import BeamableMM +from .character_token_embedder import CharacterTokenEmbedder +from .conv_tbc import ConvTBC +from .cross_entropy import cross_entropy +from .downsampled_multihead_attention import DownsampledMultiHeadAttention +from .dynamic_convolution import DynamicConv, DynamicConv1dTBC +from .dynamic_crf_layer import DynamicCRF +from .ema_module import EMAModuleConfig, EMAModule +from .fairseq_dropout import FairseqDropout +from .fp32_batch_norm import Fp32BatchNorm +from .fp32_group_norm import Fp32GroupNorm +from .fp32_instance_norm import Fp32InstanceNorm +from .gelu import gelu, gelu_accurate +from .grad_multiply import GradMultiply +from .gumbel_vector_quantizer import GumbelVectorQuantizer +from .kmeans_vector_quantizer import KmeansVectorQuantizer +from .layer_drop import LayerDropModuleList +from .layer_norm import Fp32LayerNorm, LayerNorm +from .learned_positional_embedding import LearnedPositionalEmbedding +from .lightweight_convolution import LightweightConv, LightweightConv1dTBC +from .linearized_convolution import LinearizedConvolution +from .location_attention import LocationAttention +from .lstm_cell_with_zoneout import LSTMCellWithZoneOut +from .multihead_attention import MultiheadAttention +from .positional_embedding import PositionalEmbedding +from .same_pad import SamePad +from .scalar_bias import ScalarBias +from .sinusoidal_positional_embedding import SinusoidalPositionalEmbedding +from .transformer_sentence_encoder_layer import TransformerSentenceEncoderLayer +from .transformer_sentence_encoder import TransformerSentenceEncoder +from .transpose_last import TransposeLast +from .unfold import unfold1d +from .transformer_layer import TransformerDecoderLayer, TransformerEncoderLayer +from .vggblock import VGGBlock +from .espnet_multihead_attention import ( + ESPNETMultiHeadedAttention, + RelPositionMultiHeadedAttention, + RotaryPositionMultiHeadedAttention, +) +from .rotary_positional_embedding import RotaryPositionalEmbedding +from .positional_encoding import ( + RelPositionalEncoding, +) + +__all__ = [ + "AdaptiveInput", + "AdaptiveSoftmax", + "BaseLayer", + "BeamableMM", + "CharacterTokenEmbedder", + "ConvTBC", + "cross_entropy", + "DownsampledMultiHeadAttention", + "DynamicConv1dTBC", + "DynamicConv", + "DynamicCRF", + "EMAModule", + "EMAModuleConfig", + "FairseqDropout", + "Fp32BatchNorm", + "Fp32GroupNorm", + "Fp32LayerNorm", + "Fp32InstanceNorm", + "gelu", + "gelu_accurate", + "GradMultiply", + "GumbelVectorQuantizer", + "KmeansVectorQuantizer", + "LayerDropModuleList", + "LayerNorm", + "LearnedPositionalEmbedding", + "LightweightConv1dTBC", + "LightweightConv", + "LinearizedConvolution", + "LocationAttention", + "LSTMCellWithZoneOut", + "MultiheadAttention", + "PositionalEmbedding", + "SamePad", + "ScalarBias", + "SinusoidalPositionalEmbedding", + "TransformerSentenceEncoderLayer", + "TransformerSentenceEncoder", + "TransformerDecoderLayer", + "TransformerEncoderLayer", + "TransposeLast", + "VGGBlock", + "unfold1d", + "ESPNETMultiheadedAttention", + "PositionalEmbedding", + "RelPositionMultiHeadedAttention", + "RelPositionalEncoding", + "RotaryPositionalEmbedding", + "RotaryPositionMultiHeadedAttention", +] diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/adaptive_input.py b/PyTorch/NLP/new-Transformer/fairseq/modules/adaptive_input.py new file mode 100644 index 00000000..01ac4acc --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/adaptive_input.py @@ -0,0 +1,81 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from typing import List + +import torch +from torch import nn + +from fairseq.modules.quant_noise import quant_noise + + +class AdaptiveInput(nn.Module): + def __init__( + self, + vocab_size: int, + padding_idx: int, + initial_dim: int, + factor: float, + output_dim: int, + cutoff: List[int], + q_noise: float = 0, + qn_block_size: int = 8, + ): + super().__init__() + + if vocab_size > cutoff[-1]: + cutoff = cutoff + [vocab_size] + else: + assert ( + vocab_size == cutoff[-1] + ), "cannot specify cutoff larger than vocab size" + + self.cutoff = cutoff + self.embedding_dim = output_dim + self.padding_idx = padding_idx + + self.embeddings = nn.ModuleList() + for i in range(len(self.cutoff)): + prev = self.cutoff[i - 1] if i > 0 else 0 + size = self.cutoff[i] - prev + dim = int(initial_dim // (factor**i)) + seq = nn.Sequential( + nn.Embedding(size, dim, self.padding_idx), + quant_noise( + nn.Linear(dim, output_dim, bias=False), q_noise, qn_block_size + ), + ) + + self.embeddings.append(seq) + self.padding_idx = None + self.padding_idx = padding_idx + + def init_weights(m): + if isinstance(m, nn.Embedding): + nn.init.normal_(m.weight, mean=0, std=m.weight.shape[1] ** -0.5) + nn.init.constant_(m.weight[padding_idx], 0) + elif hasattr(m, "weight"): + nn.init.xavier_uniform_(m.weight) + + self.apply(init_weights) + + self.register_buffer("_float_tensor", torch.FloatTensor(1)) + + def weights_for_band(self, band: int): + return self.embeddings[band][0].weight, self.embeddings[band][1].weight + + def forward(self, input: torch.Tensor): + result = self._float_tensor.new(input.shape + (self.embedding_dim,)) + for i in range(len(self.cutoff)): + mask = input.lt(self.cutoff[i]) + if i > 0: + mask.mul_(input.ge(self.cutoff[i - 1])) + chunk_input = input[mask] - self.cutoff[i - 1] + else: + chunk_input = input[mask] + if mask.any(): + result[mask] = self.embeddings[i](chunk_input) + return result diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/adaptive_softmax.py b/PyTorch/NLP/new-Transformer/fairseq/modules/adaptive_softmax.py new file mode 100644 index 00000000..ae0c77ba --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/adaptive_softmax.py @@ -0,0 +1,268 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import functools +import operator + +import torch +import torch.nn.functional as F +from fairseq.modules.fairseq_dropout import FairseqDropout +from fairseq.modules.quant_noise import quant_noise +from torch import nn + + +class TiedLinear(nn.Module): + def __init__(self, weight, transpose): + super().__init__() + self.weight = weight + self.transpose = transpose + + def forward(self, input): + return F.linear(input, self.weight.t() if self.transpose else self.weight) + + +class TiedHeadModule(nn.Module): + def __init__(self, weights, input_dim, num_classes, q_noise, qn_block_size): + super().__init__() + tied_emb, _ = weights + self.num_words, emb_dim = tied_emb.size() + + self.word_proj = quant_noise( + TiedLinear(tied_emb, transpose=False), q_noise, qn_block_size + ) + if input_dim != emb_dim: + self.word_proj = nn.Sequential( + quant_noise( + nn.Linear(input_dim, emb_dim, bias=False), q_noise, qn_block_size + ), + self.word_proj, + ) + + self.class_proj = quant_noise( + nn.Linear(input_dim, num_classes, bias=False), q_noise, qn_block_size + ) + self.out_dim = self.num_words + num_classes + + self.register_buffer("_float_tensor", torch.FloatTensor(1)) + + def forward(self, input): + inp_sz = functools.reduce(operator.mul, input.shape[:-1], 1) + out = self._float_tensor.new(inp_sz, self.out_dim) + out[:, : self.num_words] = self.word_proj(input.view(inp_sz, -1)) + out[:, self.num_words :] = self.class_proj(input.view(inp_sz, -1)) + return out + + +class AdaptiveSoftmax(nn.Module): + """ + This is an implementation of the efficient softmax approximation for + graphical processing units (GPU), described in the paper "Efficient softmax + approximation for GPUs" (http://arxiv.org/abs/1609.04309). + """ + + def __init__( + self, + vocab_size, + input_dim, + cutoff, + dropout, + factor=4.0, + adaptive_inputs=None, + tie_proj=False, + q_noise=0, + qn_block_size=8, + ): + super().__init__() + + if vocab_size > cutoff[-1]: + cutoff = cutoff + [vocab_size] + else: + assert ( + vocab_size == cutoff[-1] + ), "cannot specify cutoff larger than vocab size" + + output_dim = cutoff[0] + len(cutoff) - 1 + + self.vocab_size = vocab_size + self.cutoff = cutoff + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + self.input_dim = input_dim + self.factor = factor + self.q_noise = q_noise + self.qn_block_size = qn_block_size + + self.lsm = nn.LogSoftmax(dim=1) + + if adaptive_inputs is not None: + self.head = TiedHeadModule( + adaptive_inputs.weights_for_band(0), + input_dim, + len(cutoff) - 1, + self.q_noise, + self.qn_block_size, + ) + else: + self.head = quant_noise( + nn.Linear(input_dim, output_dim, bias=False), + self.q_noise, + self.qn_block_size, + ) + + self._make_tail(adaptive_inputs, tie_proj) + + def init_weights(m): + if ( + hasattr(m, "weight") + and not isinstance(m, TiedLinear) + and not isinstance(m, TiedHeadModule) + ): + nn.init.xavier_uniform_(m.weight) + + self.apply(init_weights) + + self.register_buffer("version", torch.LongTensor([1])) + + def _make_tail(self, adaptive_inputs=None, tie_proj=False): + self.tail = nn.ModuleList() + for i in range(len(self.cutoff) - 1): + dim = int(self.input_dim // self.factor ** (i + 1)) + + tied_emb, tied_proj = ( + adaptive_inputs.weights_for_band(i + 1) + if adaptive_inputs is not None + else (None, None) + ) + + if tied_proj is not None: + if tie_proj: + proj = quant_noise( + TiedLinear(tied_proj, transpose=True), + self.q_noise, + self.qn_block_size, + ) + else: + proj = quant_noise( + nn.Linear(tied_proj.size(0), tied_proj.size(1), bias=False), + self.q_noise, + self.qn_block_size, + ) + else: + proj = quant_noise( + nn.Linear(self.input_dim, dim, bias=False), + self.q_noise, + self.qn_block_size, + ) + + if tied_emb is None: + out_proj = nn.Linear( + dim, self.cutoff[i + 1] - self.cutoff[i], bias=False + ) + else: + out_proj = TiedLinear(tied_emb, transpose=False) + + m = nn.Sequential( + proj, + nn.Dropout(self.dropout_module.p), + quant_noise(out_proj, self.q_noise, self.qn_block_size), + ) + + self.tail.append(m) + + def upgrade_state_dict_named(self, state_dict, name): + version_name = name + ".version" + if version_name not in state_dict: + raise Exception("This version of the model is no longer supported") + + def adapt_target(self, target): + """ + In order to be efficient, the AdaptiveSoftMax does not compute the + scores for all the word of the vocabulary for all the examples. It is + thus necessary to call the method adapt_target of the AdaptiveSoftMax + layer inside each forward pass. + """ + + target = target.view(-1) + new_target = [target.clone()] + target_idxs = [] + + for i in range(len(self.cutoff) - 1): + mask = target.ge(self.cutoff[i]).mul(target.lt(self.cutoff[i + 1])) + new_target[0][mask] = self.cutoff[0] + i + + if mask.any(): + target_idxs.append(mask.nonzero(as_tuple=False).squeeze(1)) + new_target.append(target[mask].add(-self.cutoff[i])) + else: + target_idxs.append(None) + new_target.append(None) + + return new_target, target_idxs + + def forward(self, input, target): + """ + Args: + input: (b x t x d) + target: (b x t) + Returns: + 2 lists: output for each cutoff section and new targets by cut off + """ + + input = input.contiguous().view(-1, input.size(-1)) + input = self.dropout_module(input) + + new_target, target_idxs = self.adapt_target(target) + output = [self.head(input)] + + for i in range(len(target_idxs)): + if target_idxs[i] is not None: + output.append(self.tail[i](input.index_select(0, target_idxs[i]))) + else: + output.append(None) + + return output, new_target + + def get_log_prob(self, input, target): + """ + Computes the log probabilities for all the words of the vocabulary, + given a 2D tensor of hidden vectors. + """ + + bsz, length, dim = input.size() + input = input.contiguous().view(-1, dim) + + if target is not None: + _, target_idxs = self.adapt_target(target) + else: + target_idxs = None + + head_y = self.head(input) + log_probs = head_y.new_zeros(input.size(0), self.vocab_size) + + head_sz = self.cutoff[0] + len(self.tail) + log_probs[:, :head_sz] = self.lsm(head_y) + tail_priors = log_probs[:, self.cutoff[0] : head_sz].clone() + + for i in range(len(self.tail)): + start = self.cutoff[i] + end = self.cutoff[i + 1] + + if target_idxs is None: + tail_out = log_probs[:, start:end] + tail_out.copy_(self.tail[i](input)) + log_probs[:, start:end] = self.lsm(tail_out).add_( + tail_priors[:, i, None] + ) + elif target_idxs[i] is not None: + idxs = target_idxs[i] + tail_out = log_probs[idxs, start:end] + tail_out.copy_(self.tail[i](input[idxs])) + log_probs[idxs, start:end] = self.lsm(tail_out).add_( + tail_priors[idxs, i, None] + ) + + log_probs = log_probs.view(bsz, length, -1) + return log_probs diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/base_layer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/base_layer.py new file mode 100644 index 00000000..e823f7ba --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/base_layer.py @@ -0,0 +1,170 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn as nn +import torch +import sys +from fairseq import utils +from fairseq.distributed import utils as distributed_utils +from fairseq.modules.layer_norm import LayerNorm + + +class BaseLayer(nn.Module): + def __init__(self, args): + super().__init__() + self.num_workers = distributed_utils.get_data_parallel_world_size() + expert_centroids = torch.empty(self.num_workers, args.decoder_embed_dim) + torch.nn.init.orthogonal_(expert_centroids, gain=0.1) + self.register_parameter( + "expert_centroids", torch.nn.Parameter(expert_centroids) + ) + self.expert_network = nn.Sequential( + *([BaseSublayer(args) for _ in range(args.base_sublayers)]) + ) + self.expert_id = distributed_utils.get_data_parallel_rank() + self.shuffle = args.base_shuffle + self.cpp = self.load_assignment() + + # Add a special attribute to the expert parameters, so we know not to sync their gradients + for param in self.expert_network.parameters(): + param.expert = True + + def forward(self, input_features, *args, **kwargs): + features = input_features.reshape(-1, input_features.size(-1)) + is_training = input_features.requires_grad + + if self.shuffle and is_training: + # Send each token to a random worker, to break correlations within the batch + shuffle_sort = torch.randperm(features.size(0), device=features.device) + features = All2All.apply(features[shuffle_sort]) + + with torch.no_grad(): + # Compute similarity of each token to each expert, for routing + token_expert_affinities = features.matmul( + self.expert_centroids.transpose(0, 1) + ) + + # Compute which token goes to which expert + sort_by_expert, input_splits, output_splits = ( + self.balanced_assignment(token_expert_affinities) + if is_training + else self.greedy_assignment(token_expert_affinities) + ) + # Swap these tokens for the right ones for our expert + routed_features = All2All.apply( + features[sort_by_expert], output_splits, input_splits + ) + + if routed_features.size(0) > 0: + # Mix in the expert network based on how appropriate it is for these tokens + alpha = torch.sigmoid( + routed_features.mv(self.expert_centroids[self.expert_id]) + ).unsqueeze(1) + routed_features = ( + alpha * self.expert_network(routed_features) + + (1 - alpha) * routed_features + ) + # Return to original worker and ordering + result = All2All.apply(routed_features, input_splits, output_splits)[ + self.inverse_sort(sort_by_expert) + ] + + if self.shuffle and is_training: + # Undo shuffling + result = All2All.apply(result)[self.inverse_sort(shuffle_sort)] + + # Return additional Nones for compatibility with TransformerDecoderLayer + return result.view(input_features.size()), None, None + + def inverse_sort(self, order): + # Creates an index that undoes a sort: xs==xs[order][inverse_sort(order)] + return torch.empty_like(order).scatter_( + 0, order, torch.arange(0, order.size(0), device=order.device) + ) + + def balanced_assignment(self, scores): + ok = scores.isfinite() + if not ok.all(): + # NaNs here can break the assignment algorithm + scores[~ok] = scores[ok].min() + return self.cpp.balanced_assignment(scores), None, None + + # Assigns each token to the top k experts + def greedy_assignment(self, scores, k=1): + token_to_workers = torch.topk(scores, dim=1, k=k, largest=True).indices.view(-1) + token_to_workers, sort_ordering = torch.sort(token_to_workers) + worker2token = sort_ordering // k + + # Find how many tokens we're sending to each other worker (being careful for sending 0 tokens to some workers) + output_splits = torch.zeros( + (self.num_workers,), dtype=torch.long, device=scores.device + ) + workers, counts = torch.unique_consecutive(token_to_workers, return_counts=True) + output_splits[workers] = counts + # Tell other workers how many tokens to expect from us + input_splits = All2All.apply(output_splits) + return worker2token, input_splits.tolist(), output_splits.tolist() + + def load_assignment(self): + try: + from fairseq import libbase + + return libbase + + except ImportError as e: + sys.stderr.write( + "ERROR: missing libbase. run `python setup.py build_ext --inplace`\n" + ) + raise e + + +class BaseSublayer(nn.Module): + def __init__(self, args): + super().__init__() + self.activation_fn = utils.get_activation_fn( + activation=getattr(args, "activation_fn", "relu") or "relu" + ) + self.norm = LayerNorm(args.decoder_embed_dim, export=False) + self.ff1 = torch.nn.Linear(args.decoder_embed_dim, args.decoder_ffn_embed_dim) + self.ff2 = torch.nn.Linear(args.decoder_ffn_embed_dim, args.decoder_embed_dim) + self.ff2.weight.data.zero_() + + def forward(self, xs): + return xs + self.ff2(self.activation_fn(self.ff1(self.norm(xs)))) + + +# Wraps torch.distributed.all_to_all_single as a function that supports autograd +class All2All(torch.autograd.Function): + @staticmethod + def forward(ctx, xs, input_splits=None, output_splits=None): + ctx.input_splits = input_splits + ctx.output_splits = output_splits + + ys = ( + torch.empty_like(xs) + if output_splits is None + else xs.new_empty(size=[sum(output_splits)] + list(xs.size()[1:])) + ) + torch.distributed.all_to_all_single( + ys, xs, output_split_sizes=output_splits, input_split_sizes=input_splits + ) + return ys + + @staticmethod + def backward(ctx, grad_output): + result = ( + torch.empty_like(grad_output) + if ctx.input_splits is None + else grad_output.new_empty( + size=[sum(ctx.input_splits)] + list(grad_output.size()[1:]) + ) + ) + torch.distributed.all_to_all_single( + result, + grad_output, + output_split_sizes=ctx.input_splits, + input_split_sizes=ctx.output_splits, + ) + return result, None, None diff --git a/PyTorch/NLP/Transformer/fairseq/modules/beamable_mm.py b/PyTorch/NLP/new-Transformer/fairseq/modules/beamable_mm.py similarity index 71% rename from PyTorch/NLP/Transformer/fairseq/modules/beamable_mm.py rename to PyTorch/NLP/new-Transformer/fairseq/modules/beamable_mm.py index b0ece04c..eff1a460 100644 --- a/PyTorch/NLP/Transformer/fairseq/modules/beamable_mm.py +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/beamable_mm.py @@ -1,9 +1,7 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. +# Copyright (c) Facebook, Inc. and its affiliates. # -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. import torch import torch.nn as nn @@ -17,16 +15,18 @@ class BeamableMM(nn.Module): inference by replacing the inputs {(bsz x 1 x nhu), (bsz x sz2 x nhu)} with smaller inputs {(bsz/beam x beam x nhu), (bsz/beam x sz2 x nhu)}. """ + def __init__(self, beam_size=None): super(BeamableMM, self).__init__() self.beam_size = beam_size def forward(self, input1, input2): if ( - not self.training and # test mode - self.beam_size is not None and # beam size is set - input1.dim() == 3 and # only support batched input - input1.size(1) == 1 # single time step update + not self.training + and self.beam_size is not None # test mode + and input1.dim() == 3 # beam size is set + and input1.size(1) # only support batched input + == 1 # single time step update ): bsz, beam = input1.size(0), self.beam_size diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/character_token_embedder.py b/PyTorch/NLP/new-Transformer/fairseq/modules/character_token_embedder.py new file mode 100644 index 00000000..181221b6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/character_token_embedder.py @@ -0,0 +1,214 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from typing import List, Tuple + +import torch +import torch.nn.functional as F +from fairseq.data import Dictionary +from torch import nn + + +CHAR_PAD_IDX = 0 +CHAR_EOS_IDX = 257 + + +logger = logging.getLogger(__name__) + + +class CharacterTokenEmbedder(torch.nn.Module): + def __init__( + self, + vocab: Dictionary, + filters: List[Tuple[int, int]], + char_embed_dim: int, + word_embed_dim: int, + highway_layers: int, + max_char_len: int = 50, + char_inputs: bool = False, + ): + super(CharacterTokenEmbedder, self).__init__() + + self.onnx_trace = False + self.embedding_dim = word_embed_dim + self.max_char_len = max_char_len + self.char_embeddings = nn.Embedding(257, char_embed_dim, padding_idx=0) + self.symbol_embeddings = nn.Parameter(torch.FloatTensor(2, word_embed_dim)) + self.eos_idx, self.unk_idx = 0, 1 + self.char_inputs = char_inputs + + self.convolutions = nn.ModuleList() + for width, out_c in filters: + self.convolutions.append( + nn.Conv1d(char_embed_dim, out_c, kernel_size=width) + ) + + last_dim = sum(f[1] for f in filters) + + self.highway = Highway(last_dim, highway_layers) if highway_layers > 0 else None + + self.projection = nn.Linear(last_dim, word_embed_dim) + + assert ( + vocab is not None or char_inputs + ), "vocab must be set if not using char inputs" + self.vocab = None + if vocab is not None: + self.set_vocab(vocab, max_char_len) + + self.reset_parameters() + + def prepare_for_onnx_export_(self): + self.onnx_trace = True + + def set_vocab(self, vocab, max_char_len): + word_to_char = torch.LongTensor(len(vocab), max_char_len) + + truncated = 0 + for i in range(len(vocab)): + if i < vocab.nspecial: + char_idxs = [0] * max_char_len + else: + chars = vocab[i].encode() + # +1 for padding + char_idxs = [c + 1 for c in chars] + [0] * (max_char_len - len(chars)) + if len(char_idxs) > max_char_len: + truncated += 1 + char_idxs = char_idxs[:max_char_len] + word_to_char[i] = torch.LongTensor(char_idxs) + + if truncated > 0: + logger.info( + "truncated {} words longer than {} characters".format( + truncated, max_char_len + ) + ) + + self.vocab = vocab + self.word_to_char = word_to_char + + @property + def padding_idx(self): + return Dictionary().pad() if self.vocab is None else self.vocab.pad() + + def reset_parameters(self): + nn.init.xavier_normal_(self.char_embeddings.weight) + nn.init.xavier_normal_(self.symbol_embeddings) + nn.init.xavier_uniform_(self.projection.weight) + + nn.init.constant_( + self.char_embeddings.weight[self.char_embeddings.padding_idx], 0.0 + ) + nn.init.constant_(self.projection.bias, 0.0) + + def forward( + self, + input: torch.Tensor, + ): + if self.char_inputs: + chars = input.view(-1, self.max_char_len) + pads = chars[:, 0].eq(CHAR_PAD_IDX) + eos = chars[:, 0].eq(CHAR_EOS_IDX) + if eos.any(): + if self.onnx_trace: + chars = torch.where(eos.unsqueeze(1), chars.new_zeros(1), chars) + else: + chars[eos] = 0 + + unk = None + else: + flat_words = input.view(-1) + chars = self.word_to_char[flat_words.type_as(self.word_to_char)].type_as( + input + ) + pads = flat_words.eq(self.vocab.pad()) + eos = flat_words.eq(self.vocab.eos()) + unk = flat_words.eq(self.vocab.unk()) + + word_embs = self._convolve(chars) + if self.onnx_trace: + if pads.any(): + word_embs = torch.where( + pads.unsqueeze(1), word_embs.new_zeros(1), word_embs + ) + if eos.any(): + word_embs = torch.where( + eos.unsqueeze(1), self.symbol_embeddings[self.eos_idx], word_embs + ) + if unk is not None and unk.any(): + word_embs = torch.where( + unk.unsqueeze(1), self.symbol_embeddings[self.unk_idx], word_embs + ) + else: + if pads.any(): + word_embs[pads] = 0 + if eos.any(): + word_embs[eos] = self.symbol_embeddings[self.eos_idx] + if unk is not None and unk.any(): + word_embs[unk] = self.symbol_embeddings[self.unk_idx] + + return word_embs.view(input.size()[:2] + (-1,)) + + def _convolve( + self, + char_idxs: torch.Tensor, + ): + char_embs = self.char_embeddings(char_idxs) + char_embs = char_embs.transpose(1, 2) # BTC -> BCT + + conv_result = [] + + for conv in self.convolutions: + x = conv(char_embs) + x, _ = torch.max(x, -1) + x = F.relu(x) + conv_result.append(x) + + x = torch.cat(conv_result, dim=-1) + + if self.highway is not None: + x = self.highway(x) + x = self.projection(x) + + return x + + +class Highway(torch.nn.Module): + """ + A `Highway layer `_. + Adopted from the AllenNLP implementation. + """ + + def __init__(self, input_dim: int, num_layers: int = 1): + super(Highway, self).__init__() + self.input_dim = input_dim + self.layers = nn.ModuleList( + [nn.Linear(input_dim, input_dim * 2) for _ in range(num_layers)] + ) + self.activation = nn.ReLU() + + self.reset_parameters() + + def reset_parameters(self): + for layer in self.layers: + # As per comment in AllenNLP: + # We should bias the highway layer to just carry its input forward. We do that by + # setting the bias on `B(x)` to be positive, because that means `g` will be biased to + # be high, so we will carry the input forward. The bias on `B(x)` is the second half + # of the bias vector in each Linear layer. + nn.init.constant_(layer.bias[self.input_dim :], 1) + + nn.init.constant_(layer.bias[: self.input_dim], 0) + nn.init.xavier_normal_(layer.weight) + + def forward(self, x: torch.Tensor): + for layer in self.layers: + projection = layer(x) + proj_x, gate = projection.chunk(2, dim=-1) + proj_x = self.activation(proj_x) + gate = torch.sigmoid(gate) + x = gate * x + (gate.new_tensor([1]) - gate) * proj_x + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/checkpoint_activations.py b/PyTorch/NLP/new-Transformer/fairseq/modules/checkpoint_activations.py new file mode 100644 index 00000000..aa0b5929 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/checkpoint_activations.py @@ -0,0 +1,242 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import functools +from typing import Any, Dict, List, Tuple, Union + +import torch +import torch.utils.checkpoint as checkpoint +from fairseq import utils + + +def checkpoint_wrapper(m, offload_to_cpu=False): + """ + A friendlier wrapper for performing activation checkpointing. + + Compared to the PyTorch version, this version: + - wraps an nn.Module, so that all subsequent calls will use checkpointing + - handles keyword arguments in the forward + - handles non-Tensor outputs from the forward + + Usage:: + + checkpointed_module = checkpoint_wrapper(my_module, offload_to_cpu=True) + a, b = checkpointed_module(x, y=3, z=torch.Tensor([1])) + """ + # should I check whether original_forward has already been set? + assert not hasattr( + m, "precheckpoint_forward" + ), "checkpoint function has already been applied?" + m.precheckpoint_forward = m.forward + m.forward = functools.partial( + _checkpointed_forward, + m.precheckpoint_forward, # original_forward + offload_to_cpu, + ) + return m + + +def unwrap_checkpoint(m: torch.nn.Module): + """ + unwrap a module and its children from checkpoint_wrapper + """ + for module in m.modules(): + if hasattr(module, "precheckpoint_forward"): + module.forward = module.precheckpoint_forward + del module.precheckpoint_forward + if hasattr(module, "old_deepcopy_method"): + module.__deepcopy__ = module.old_deepcopy_method + del module.old_deepcopy_method + return m + + +def _checkpointed_forward(original_forward, offload_to_cpu, *args, **kwargs): + # Autograd Functions in PyTorch work best with positional args, since + # the backward must return gradients (or None) for every input argument. + # We can flatten keyword arguments to make this easier. + kwarg_keys, flat_args = pack_kwargs(*args, **kwargs) + parent_ctx_dict = {"offload": offload_to_cpu} + output = CheckpointFunction.apply( + original_forward, parent_ctx_dict, kwarg_keys, *flat_args + ) + if isinstance(output, torch.Tensor): + return output + else: + packed_non_tensor_outputs = parent_ctx_dict["packed_non_tensor_outputs"] + if packed_non_tensor_outputs: + output = unpack_non_tensors(output, packed_non_tensor_outputs) + return output + + +def pack_kwargs(*args, **kwargs) -> Tuple[List[str], List[Any]]: + """ + Usage:: + + kwarg_keys, flat_args = pack_kwargs(1, 2, a=3, b=4) + args, kwargs = unpack_kwargs(kwarg_keys, flat_args) + assert args == [1, 2] + assert kwargs == {"a": 3, "b": 4} + """ + kwarg_keys = [] + flat_args = list(args) + for k, v in kwargs.items(): + kwarg_keys.append(k) + flat_args.append(v) + return kwarg_keys, flat_args + + +def unpack_kwargs( + kwarg_keys: List[str], flat_args: List[Any] +) -> Tuple[List[Any], Dict[str, Any]]: + if len(kwarg_keys) == 0: + return flat_args, {} + args = flat_args[: -len(kwarg_keys)] + kwargs = {k: v for k, v in zip(kwarg_keys, flat_args[-len(kwarg_keys) :])} + return args, kwargs + + +def split_non_tensors( + mixed: Union[torch.Tensor, Tuple[Any]] +) -> Tuple[Tuple[torch.Tensor], Dict[str, List[Any]]]: + """ + Usage:: + + x = torch.Tensor([1]) + y = torch.Tensor([2]) + tensors, packed_non_tensors = split_non_tensors((x, y, None, 3)) + recon = unpack_non_tensors(tensors, packed_non_tensors) + assert recon == (x, y, None, 3) + """ + if isinstance(mixed, torch.Tensor): + return (mixed,), None + tensors = [] + packed_non_tensors = {"is_tensor": [], "objects": []} + for o in mixed: + if isinstance(o, torch.Tensor): + packed_non_tensors["is_tensor"].append(True) + tensors.append(o) + else: + packed_non_tensors["is_tensor"].append(False) + packed_non_tensors["objects"].append(o) + return tuple(tensors), packed_non_tensors + + +def unpack_non_tensors( + tensors: Tuple[torch.Tensor], + packed_non_tensors: Dict[str, List[Any]], +) -> Tuple[Any]: + if packed_non_tensors is None: + return tensors + assert isinstance(packed_non_tensors, dict) + mixed = [] + is_tensor_list = packed_non_tensors["is_tensor"] + objects = packed_non_tensors["objects"] + assert len(tensors) + len(objects) == len(is_tensor_list) + obj_i = tnsr_i = 0 + for is_tensor in is_tensor_list: + if is_tensor: + mixed.append(tensors[tnsr_i]) + tnsr_i += 1 + else: + mixed.append(objects[obj_i]) + obj_i += 1 + return tuple(mixed) + + +class CheckpointFunction(torch.autograd.Function): + """Similar to the torch version, but support non-Tensor outputs. + + The caller is expected to provide a dict (*parent_ctx_dict*) that will hold + the non-Tensor outputs. These should be combined with the Tensor *outputs* + by calling ``unpack_non_tensors``. + """ + + @staticmethod + def forward(ctx, run_function, parent_ctx_dict, kwarg_keys, *args): + if torch.is_grad_enabled(): # grad may be disabled, e.g., during validation + checkpoint.check_backward_validity(args) + + ctx.run_function = run_function + ctx.kwarg_keys = kwarg_keys + ctx.fwd_rng_state = utils.get_rng_state() + + tensor_inputs, packed_non_tensor_inputs = split_non_tensors(args) + if parent_ctx_dict["offload"]: + ctx.fwd_device = tuple(x.device for x in tensor_inputs) + ctx.grad_requirements = tuple(x.requires_grad for x in tensor_inputs) + tensor_inputs = tuple( + x.to(torch.device("cpu"), non_blocking=True) for x in tensor_inputs + ) + + else: + ctx.fwd_device, ctx.grad_requirements = None, None + + ctx.save_for_backward(*tensor_inputs) + ctx.packed_non_tensor_inputs = packed_non_tensor_inputs + + with torch.no_grad(): + unpacked_args, unpacked_kwargs = unpack_kwargs(kwarg_keys, args) + outputs = run_function(*unpacked_args, **unpacked_kwargs) + + if isinstance(outputs, torch.Tensor): + return outputs + else: + # Autograd Functions don't like non-Tensor outputs. We can split the + # non-Tensor and Tensor outputs, returning the former by reference + # through *parent_ctx_dict* and returning the latter directly. + outputs, packed_non_tensor_outputs = split_non_tensors(outputs) + parent_ctx_dict["packed_non_tensor_outputs"] = packed_non_tensor_outputs + return outputs + + @staticmethod + def backward(ctx, *args): + if not torch.autograd._is_checkpoint_valid(): + raise RuntimeError( + "Checkpointing is not compatible with .grad(), please use .backward() if possible" + ) + + tensor_inputs: Tuple = ctx.saved_tensors + tensor_inputs = checkpoint.detach_variable(tensor_inputs) + if ctx.fwd_device is not None: + tensor_inputs = [ + t.to(ctx.fwd_device[i], non_blocking=True) + for i, t in enumerate(tensor_inputs) + ] + for i, need_grad in enumerate(ctx.grad_requirements): + tensor_inputs[i].requires_grad = need_grad + inputs = unpack_non_tensors(tensor_inputs, ctx.packed_non_tensor_inputs) + + # Store the current states. + bwd_rng_state = utils.get_rng_state() + + # Set the states to what it used to be before the forward pass. + utils.set_rng_state(ctx.fwd_rng_state) + + with torch.enable_grad(): + unpacked_args, unpacked_kwargs = unpack_kwargs(ctx.kwarg_keys, inputs) + outputs = ctx.run_function(*unpacked_args, **unpacked_kwargs) + tensor_outputs, _ = split_non_tensors(outputs) + # Set the states back to what it was at the start of this function. + utils.set_rng_state(bwd_rng_state) + + # Run backward() with only Tensors that require grad + outputs_with_grad = [] + args_with_grad = [] + for i in range(len(tensor_outputs)): + if tensor_outputs[i].requires_grad: + outputs_with_grad.append(tensor_outputs[i]) + args_with_grad.append(args[i]) + if len(outputs_with_grad) == 0: + raise RuntimeError( + "None of the outputs have requires_grad=True, " + "this checkpoint() is not necessary" + ) + + torch.autograd.backward(outputs_with_grad, args_with_grad) + + grads = tuple( + inp.grad if isinstance(inp, torch.Tensor) else None for inp in inputs + ) + return (None, None, None) + grads diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/conformer_layer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/conformer_layer.py new file mode 100644 index 00000000..4e29b0d8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/conformer_layer.py @@ -0,0 +1,299 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +import torch +from typing import Optional +from fairseq.modules import ( + LayerNorm, + MultiheadAttention, + ESPNETMultiHeadedAttention, + RelPositionMultiHeadedAttention, + RotaryPositionMultiHeadedAttention, +) +from fairseq.utils import get_activation_fn + + +class ConvolutionModule(torch.nn.Module): + """Convolution block used in the conformer block""" + + def __init__( + self, + embed_dim, + channels, + depthwise_kernel_size, + dropout, + activation_fn="swish", + bias=False, + export=False, + ): + """ + Args: + embed_dim: Embedding dimension + channels: Number of channels in depthwise conv layers + depthwise_kernel_size: Depthwise conv layer kernel size + dropout: dropout value + activation_fn: Activation function to use after depthwise convolution kernel + bias: If bias should be added to conv layers + export: If layernorm should be exported to jit + """ + super(ConvolutionModule, self).__init__() + assert ( + depthwise_kernel_size - 1 + ) % 2 == 0, "kernel_size should be a odd number for 'SAME' padding" + self.layer_norm = LayerNorm(embed_dim, export=export) + self.pointwise_conv1 = torch.nn.Conv1d( + embed_dim, + 2 * channels, + kernel_size=1, + stride=1, + padding=0, + bias=bias, + ) + self.glu = torch.nn.GLU(dim=1) + self.depthwise_conv = torch.nn.Conv1d( + channels, + channels, + depthwise_kernel_size, + stride=1, + padding=(depthwise_kernel_size - 1) // 2, + groups=channels, + bias=bias, + ) + self.batch_norm = torch.nn.BatchNorm1d(channels) + self.activation = get_activation_fn(activation_fn)(channels) + self.pointwise_conv2 = torch.nn.Conv1d( + channels, + embed_dim, + kernel_size=1, + stride=1, + padding=0, + bias=bias, + ) + self.dropout = torch.nn.Dropout(dropout) + + def forward(self, x): + """ + Args: + x: Input of shape B X T X C + Returns: + Tensor of shape B X T X C + """ + x = self.layer_norm(x) + # exchange the temporal dimension and the feature dimension + x = x.transpose(1, 2) + + # GLU mechanism + x = self.pointwise_conv1(x) # (batch, 2*channel, dim) + x = self.glu(x) # (batch, channel, dim) + + # 1D Depthwise Conv + x = self.depthwise_conv(x) + x = self.batch_norm(x) + x = self.activation(x) + + x = self.pointwise_conv2(x) + x = self.dropout(x) + return x.transpose(1, 2) + + +class FeedForwardModule(torch.nn.Module): + """Positionwise feed forward layer used in conformer""" + + def __init__( + self, + input_feat, + hidden_units, + dropout1, + dropout2, + activation_fn="swish", + bias=True, + ): + """ + Args: + input_feat: Input feature dimension + hidden_units: Hidden unit dimension + dropout1: dropout value for layer1 + dropout2: dropout value for layer2 + activation_fn: Name of activation function + bias: If linear layers should have bias + """ + + super(FeedForwardModule, self).__init__() + self.layer_norm = LayerNorm(input_feat) + self.w_1 = torch.nn.Linear(input_feat, hidden_units, bias=bias) + self.w_2 = torch.nn.Linear(hidden_units, input_feat, bias=bias) + self.dropout1 = torch.nn.Dropout(dropout1) + self.dropout2 = torch.nn.Dropout(dropout2) + self.activation = get_activation_fn(activation_fn)(hidden_units) + + def forward(self, x): + """ + Args: + x: Input Tensor of shape T X B X C + Returns: + Tensor of shape T X B X C + """ + x = self.layer_norm(x) + x = self.w_1(x) + x = self.activation(x) + x = self.dropout1(x) + x = self.w_2(x) + return self.dropout2(x) + + +class ConformerEncoderLayer(torch.nn.Module): + """Conformer block based on https://arxiv.org/abs/2005.08100. We currently don't support relative positional encoding in MHA""" + + def __init__( + self, + embed_dim, + ffn_embed_dim, + attention_heads, + dropout, + use_fp16, + depthwise_conv_kernel_size=31, + activation_fn="swish", + attn_type=None, + pos_enc_type="abs", + ): + """ + Args: + embed_dim: Input embedding dimension + ffn_embed_dim: FFN layer dimension + attention_heads: Number of attention heads in MHA + dropout: dropout value + depthwise_conv_kernel_size: Size of kernel in depthwise conv layer in convolution module + activation_fn: Activation function name to use in convulation block and feed forward block + attn_type: MHA implementation from ESPNET vs fairseq + pos_enc_type: Positional encoding type - abs, rope, rel_pos + """ + self.pos_enc_type = pos_enc_type + super(ConformerEncoderLayer, self).__init__() + + self.ffn1 = FeedForwardModule( + embed_dim, + ffn_embed_dim, + dropout, + dropout, + ) + + self.self_attn_layer_norm = LayerNorm(embed_dim, export=False) + self.self_attn_dropout = torch.nn.Dropout(dropout) + if attn_type == "espnet": + if self.pos_enc_type == "rel_pos": + self.self_attn = RelPositionMultiHeadedAttention( + embed_dim, + attention_heads, + dropout=dropout, + ) + elif self.pos_enc_type == "rope": + self.self_attn = RotaryPositionMultiHeadedAttention( + embed_dim, attention_heads, dropout=dropout, precision=use_fp16 + ) + elif self.pos_enc_type == "abs": + self.self_attn = ESPNETMultiHeadedAttention( + embed_dim, + attention_heads, + dropout=dropout, + ) + else: + raise Exception(f"Unsupported attention type {self.pos_enc_type}") + else: + # Default to fairseq MHA + self.self_attn = MultiheadAttention( + embed_dim, + attention_heads, + dropout=dropout, + ) + + self.conv_module = ConvolutionModule( + embed_dim=embed_dim, + channels=embed_dim, + depthwise_kernel_size=depthwise_conv_kernel_size, + dropout=dropout, + activation_fn=activation_fn, + ) + + self.ffn2 = FeedForwardModule( + embed_dim, + ffn_embed_dim, + dropout, + dropout, + activation_fn=activation_fn, + ) + self.final_layer_norm = LayerNorm(embed_dim, export=False) + + def forward( + self, + x, + encoder_padding_mask: Optional[torch.Tensor], + position_emb: Optional[torch.Tensor] = None, + ): + """ + Args: + x: Tensor of shape T X B X C + encoder_padding_mask: Optional mask tensor + positions: + Returns: + Tensor of shape T X B X C + """ + residual = x + x = self.ffn1(x) + x = x * 0.5 + residual + residual = x + x = self.self_attn_layer_norm(x) + if self.pos_enc_type == "rel_pos": + x, attn = self.self_attn( + query=x, + key=x, + value=x, + key_padding_mask=encoder_padding_mask, + pos_emb=position_emb, + need_weights=False, + ) + else: + x, attn = self.self_attn( + query=x, + key=x, + value=x, + key_padding_mask=encoder_padding_mask, + need_weights=False, + ) + x = self.self_attn_dropout(x) + x = x + residual + + residual = x + # TBC to BTC + x = x.transpose(0, 1) + x = self.conv_module(x) + # BTC to TBC + x = x.transpose(0, 1) + x = residual + x + + residual = x + x = self.ffn2(x) + + layer_result = x + + x = x * 0.5 + residual + + x = self.final_layer_norm(x) + return x, (attn, layer_result) + + +class ConformerWav2Vec2EncoderLayer(ConformerEncoderLayer): + """Encoder layer for Wav2vec2 encoder""" + + def forward( + self, + x: torch.Tensor, + self_attn_mask: torch.Tensor = None, + self_attn_padding_mask: torch.Tensor = None, + need_weights: bool = False, + att_args=None, + position_emb=None, + ): + return super().forward(x, self_attn_padding_mask, position_emb) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/conv_tbc.py b/PyTorch/NLP/new-Transformer/fairseq/modules/conv_tbc.py new file mode 100644 index 00000000..65e17ec9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/conv_tbc.py @@ -0,0 +1,53 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from torch import nn +from torch.nn.modules.utils import _single +from torch import Tensor + + +class ConvTBC(torch.nn.Module): + """1D convolution over an input of shape (time x batch x channel) + + The implementation uses gemm to perform the convolution. This implementation + is faster than cuDNN for small kernel sizes. + """ + + def __init__(self, in_channels, out_channels, kernel_size, padding=0): + super(ConvTBC, self).__init__() + self.in_channels = in_channels + self.out_channels = out_channels + self.kernel_size = _single(kernel_size) + self.padding = _single(padding) + + self.weight = torch.nn.Parameter( + torch.Tensor(self.kernel_size[0], in_channels, out_channels) + ) + self.bias = torch.nn.Parameter(torch.Tensor(out_channels)) + + self.reset_parameters() + + def reset_parameters(self): + nn.init.xavier_normal_(self.weight) + nn.init.zeros_(self.bias) + + def conv_tbc(self, input: Tensor): + return torch.conv_tbc( + input.contiguous(), self.weight, self.bias, self.padding[0] + ) + + def forward(self, input: Tensor): + return self.conv_tbc(input) + + def __repr__(self): + s = ( + "{name}({in_channels}, {out_channels}, kernel_size={kernel_size}" + ", padding={padding}" + ) + if self.bias is None: + s += ", bias=False" + s += ")" + return s.format(name=self.__class__.__name__, **self.__dict__) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/cross_entropy.py b/PyTorch/NLP/new-Transformer/fairseq/modules/cross_entropy.py new file mode 100644 index 00000000..286c00ee --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/cross_entropy.py @@ -0,0 +1,59 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch +import torch.nn.functional as F + +logger = logging.getLogger(__name__) + + +def _cross_entropy_pytorch(logits, target, ignore_index=None, reduction="mean"): + lprobs = F.log_softmax(logits, dim=-1, dtype=torch.float32) + return F.nll_loss( + lprobs, + target, + ignore_index=ignore_index, + reduction=reduction, + ) + + +try: + import xentropy_cuda + from apex.contrib import xentropy + + def cross_entropy(logits, target, ignore_index=-100, reduction="mean"): + if logits.device == torch.device("cpu"): + return _cross_entropy_pytorch(logits, target, ignore_index, reduction) + else: + if not getattr(cross_entropy, "_has_logged_once", False): + logger.info("using fused cross entropy") + cross_entropy._has_logged_once = True + + half_to_float = logits.dtype == torch.half + losses = xentropy.SoftmaxCrossEntropyLoss.apply( + logits, + target, + 0.0, + ignore_index, + half_to_float, + ) + if reduction == "sum": + return losses.sum() + elif reduction == "mean": + if ignore_index >= 0: + return losses.sum() / target.ne(ignore_index).sum() + else: + return losses.mean() + elif reduction == "none": + return losses + else: + raise NotImplementedError + +except ImportError: + + def cross_entropy(logits, target, ignore_index=-100, reduction="mean"): + return _cross_entropy_pytorch(logits, target, ignore_index, reduction) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/cuda_utils.cu b/PyTorch/NLP/new-Transformer/fairseq/modules/cuda_utils.cu new file mode 100644 index 00000000..924f8527 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/cuda_utils.cu @@ -0,0 +1,202 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +template +constexpr __host__ __device__ auto divUp(U a, V b) -> decltype(a + b) { + return (a + b - 1) / b; +} + +template +__inline__ __device__ void zeroSharedMem(scalar_t* data) { + /* + Given an array of length FS + SB, zero out the first padding_l and last + (FS - padding_l) values in the array + */ + + int tid = threadIdx.x; + + if (FS < SB) { + // zero all if we have enough threads in a block to do all of them + if (tid < padding_l || tid > SB - FS + padding_l - 1) { + data[tid] = scalar_t(0.0); + } + } else { + // otherwise zero out one block at a time + const int numIterations = divUp(FS, SB); + for (int i = 0; i < numIterations; i++) { + int offset = i * SB; + if (tid + offset < padding_l) { + data[tid + offset] = scalar_t(0.0); + } else if (tid + offset < FS) { + data[SB + tid + offset] = scalar_t(0.0); + } + } + } +} + +template +__inline__ __device__ scalar_t warpReduce(scalar_t data) { + /* + Reduce an array within each warp. After processing all values in warp will + caontain the sum of all original values in that warp. + + data - pointer to data to reduce + */ + data += __shfl_xor_sync(SHFL_MASK, data, 16); + data += __shfl_xor_sync(SHFL_MASK, data, 8); + data += __shfl_xor_sync(SHFL_MASK, data, 4); + data += __shfl_xor_sync(SHFL_MASK, data, 2); + data += __shfl_xor_sync(SHFL_MASK, data, 1); + return data; +} + +template +__inline__ __device__ scalar_t blockReduce(scalar_t data) { + /* + Reduce an entire array on the block level. After processing, the + first value in the array will contain the reduced sum. + + data - pointer to data to reduce + */ + + static __shared__ scalar_t warpSum[32]; + const int tid = threadIdx.x; + int wid = tid / 32; + int lane = tid % 32; + + __syncthreads(); + + // reduce each warp then write to shared memory + scalar_t sum = warpReduce(data); + if (lane == 0) { + warpSum[wid] = sum; + } + + __syncthreads(); + + scalar_t v; + // perform final sum of partial warp sums + if (tid < blockDim.x / 32) { + v = warpSum[lane]; + } else { + v = scalar_t(0.0); + } + + if (wid == 0) { + v = warpReduce(v); + } + __syncthreads(); + + return v; +} + +void checkCudaStatus(cudaError_t status, int lineNumber = -1) { + if (status != cudaSuccess) { + std::cout << cudaGetErrorString(status) << " at line " << lineNumber + << std::endl; + std::cout << "Exiting" << std::endl; + exit(1); + } +} + +template +__device__ void load_input_to_shared( + const scalar_t* input, // global memory + int inputOffset, + int sequenceLength, + int iteration, + int numIterations, + bool no_prev, + scalar_t* output /* shared memory */) { + /* + Load a block size of input into shared memory with + right and left overhang of total size FS. If previously + loaded memory, overlap will be shifted over to reduce + global memory access + + input - pointer to start of channel sequence + inputOffset - how far in the sequence to start loading + sequenceLength - total length of sequence + iteration - which block of sequence we are loading + numIterations - total number of blocks to load + no_prev - whether to load the whole block if the previous block + wasn't loaded + output - shared memory to write input to + */ + + const int tid = threadIdx.x; + + // Load the left "overhang" of input + if (iteration > 0) { + if (padding_l < SB) { + // load all at once + if (tid < padding_l) { + output[tid] = + (no_prev) ? input[inputOffset - padding_l + tid] : output[tid + SB]; + } + } else { + // load in chunks of size SB + int numIterations = divUp(padding_l, SB); + for (int i = 0; i < numIterations; i++) { + int offset = i * SB; + if ((tid + offset) < padding_l) { + output[tid + offset] = (no_prev) + ? input[inputOffset - padding_l + tid + offset] + : output[tid + offset + SB]; + } + } + } + } + + // Load the right "overhang" of input + if (iteration < (numIterations - 1)) { + const int elementsLeft = sequenceLength - (iteration + 1) * SB; + + if ((FS - padding_l) < SB) { + // load all at once + if (tid < (FS - padding_l)) { + output[padding_l + SB + tid] = (tid < elementsLeft) + ? input[inputOffset + SB + tid] + : scalar_t(0.0); + } + } else { + // load in chunks of size SB + int numIterations = divUp(FS - padding_l, SB); + for (int i = 0; i < numIterations; i++) { + int offset = i * SB; + if ((tid + offset) < (FS - padding_l)) { + output[padding_l + SB + tid + offset] = + ((tid + offset) < elementsLeft) + ? input[inputOffset + SB + tid + offset] + : scalar_t(0.0); + } + } + } + } + + // We should also clear out the right "overhang" + if (iteration == (numIterations - 1)) { + if ((FS - padding_l) < SB) { + // clear out all at once + if (tid < (FS - padding_l)) { + output[padding_l + SB + tid] = scalar_t(0.0); + } + } else { + // clear in chunks of size SB + int numIterations = divUp(FS - padding_l, SB); + for (int i = 0; i < numIterations; i++) { + int offset = i * SB; + if ((tid + offset) < (FS - padding_l)) { + output[padding_l + SB + tid + offset] = scalar_t(0.0); + } + } + } + } + output[tid + padding_l] = ((inputOffset + tid) < sequenceLength) + ? input[inputOffset + tid] + : scalar_t(0.0); +} diff --git a/PyTorch/NLP/Transformer/fairseq/modules/downsampled_multihead_attention.py b/PyTorch/NLP/new-Transformer/fairseq/modules/downsampled_multihead_attention.py similarity index 71% rename from PyTorch/NLP/Transformer/fairseq/modules/downsampled_multihead_attention.py rename to PyTorch/NLP/new-Transformer/fairseq/modules/downsampled_multihead_attention.py index d9de0730..5e42942a 100644 --- a/PyTorch/NLP/Transformer/fairseq/modules/downsampled_multihead_attention.py +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/downsampled_multihead_attention.py @@ -1,9 +1,7 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. +# Copyright (c) Facebook, Inc. and its affiliates. # -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. # import math @@ -11,6 +9,8 @@ import math import torch import torch.nn as nn import torch.nn.functional as F + +from fairseq.modules.fairseq_dropout import FairseqDropout from fairseq.modules.scalar_bias import scalar_bias @@ -18,14 +18,25 @@ class SingleHeadAttention(nn.Module): """ Single-head attention that supports Gating and Downsampling """ + def __init__( - self, out_channels, embed_dim, head_dim, head_index, dropout=0., - bias=True, project_input=True, gated=False, downsample=False, + self, + out_channels, + embed_dim, + head_dim, + head_index, + dropout=0.0, + bias=True, + project_input=True, + gated=False, + downsample=False, num_heads=1, ): super().__init__() self.embed_dim = embed_dim - self.dropout = dropout + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) self.head_index = head_index self.head_dim = head_dim self.project_input = project_input @@ -62,8 +73,13 @@ class SingleHeadAttention(nn.Module): self.scaling = self.head_dim**-0.5 def forward( - self, query, key, value, mask_future_timesteps=False, - key_padding_mask=None, use_scalar_bias=False, + self, + query, + key, + value, + mask_future_timesteps=False, + key_padding_mask=None, + use_scalar_bias=False, ): """Input shape: Time x Batch x Channel Self-attention can be implemented by passing in the same arguments for @@ -107,16 +123,17 @@ class SingleHeadAttention(nn.Module): attn_weights = torch.bmm(q, k.transpose(1, 2)) if mask_future_timesteps: - assert query.size() == key.size(), \ - 'mask_future_timesteps only applies to self-attention' + assert ( + query.size() == key.size() + ), "mask_future_timesteps only applies to self-attention" attn_weights *= torch.tril( attn_weights.data.new([1]).expand(tgt_len, tgt_len).clone(), diagonal=-1, - )[:, ::self.head_index + 1 if self.downsample else 1].unsqueeze(0) + )[:, :: self.head_index + 1 if self.downsample else 1].unsqueeze(0) attn_weights += torch.triu( attn_weights.data.new([-math.inf]).expand(tgt_len, tgt_len).clone(), - diagonal=0 - )[:, ::self.head_index + 1 if self.downsample else 1].unsqueeze(0) + diagonal=0, + )[:, :: self.head_index + 1 if self.downsample else 1].unsqueeze(0) tgt_size = tgt_len if use_scalar_bias: attn_weights = scalar_bias(attn_weights, 2) @@ -129,14 +146,16 @@ class SingleHeadAttention(nn.Module): if self.downsample: attn_weights = attn_weights.view(bsz, 1, tgt_len, src_len) else: - attn_weights = attn_weights.view(size, self.num_heads, tgt_len, src_len) + attn_weights = attn_weights.view( + size, self.num_heads, tgt_len, src_len + ) attn_weights = attn_weights.masked_fill( key_padding_mask.unsqueeze(1).unsqueeze(2), -math.inf, ) attn_weights = attn_weights.view(size, tgt_len, src_len) attn_weights = F.softmax(attn_weights, dim=-1) - attn_weights = F.dropout(attn_weights, p=self.dropout, training=self.training) + attn_weights = self.dropout_module(attn_weights) attn = torch.bmm(attn_weights, v) if self.downsample: @@ -153,13 +172,20 @@ class DownsampledMultiHeadAttention(nn.ModuleList): """ Multi-headed attention with Gating and Downsampling """ + def __init__( - self, out_channels, embed_dim, num_heads, dropout=0., bias=True, - project_input=True, gated=False, downsample=False, + self, + out_channels, + embed_dim, + num_heads, + dropout=0.0, + bias=True, + project_input=True, + gated=False, + downsample=False, ): self.embed_dim = embed_dim self.num_heads = num_heads - self.dropout = dropout self.head_dim = embed_dim // num_heads self.downsample = downsample self.gated = gated @@ -171,9 +197,16 @@ class DownsampledMultiHeadAttention(nn.ModuleList): for index in range(self.num_heads): attention_heads.append( SingleHeadAttention( - out_channels, self.embed_dim, self.head_dim, index, - self.dropout, bias, self.project_input, self.gated, - self.downsample, self.num_heads, + out_channels, + self.embed_dim, + self.head_dim, + index, + dropout, + bias, + self.project_input, + self.gated, + self.downsample, + self.num_heads, ) ) super().__init__(modules=attention_heads) @@ -183,13 +216,26 @@ class DownsampledMultiHeadAttention(nn.ModuleList): # if not being downsampled, we can do the heads with one linear layer instead of separate ones super().__init__() self.attention_module = SingleHeadAttention( - out_channels, self.embed_dim, self.head_dim, 1, self.dropout, - bias, self.project_input, self.gated, self.downsample, self.num_heads, + out_channels, + self.embed_dim, + self.head_dim, + 1, + dropout, + bias, + self.project_input, + self.gated, + self.downsample, + self.num_heads, ) def forward( - self, query, key, value, mask_future_timesteps=False, - key_padding_mask=None, use_scalar_bias=False, + self, + query, + key, + value, + mask_future_timesteps=False, + key_padding_mask=None, + use_scalar_bias=False, ): src_len, bsz, embed_dim = key.size() tgt_len = query.size(0) @@ -207,7 +253,12 @@ class DownsampledMultiHeadAttention(nn.ModuleList): for attention_head_number in range(self.num_heads): # call the forward of each attention head _attn, _attn_weight = self[attention_head_number]( - query, key, value, mask_future_timesteps, key_padding_mask, use_scalar_bias, + query, + key, + value, + mask_future_timesteps, + key_padding_mask, + use_scalar_bias, ) attn.append(_attn) attn_weights.append(_attn_weight) @@ -216,13 +267,20 @@ class DownsampledMultiHeadAttention(nn.ModuleList): return full_attn, attn_weights[0].clone() else: _attn, _attn_weight = self.attention_module( - query, key, value, mask_future_timesteps, key_padding_mask, use_scalar_bias, + query, + key, + value, + mask_future_timesteps, + key_padding_mask, + use_scalar_bias, ) attn.append(_attn) attn_weights.append(_attn_weight) full_attn = torch.cat(attn, dim=2) full_attn_weights = torch.cat(attn_weights) - full_attn_weights = full_attn_weights.view(bsz, self.num_heads, tgt_size, src_len) + full_attn_weights = full_attn_weights.view( + bsz, self.num_heads, tgt_size, src_len + ) full_attn_weights = full_attn_weights.sum(dim=1) / self.num_heads return full_attn, full_attn_weights @@ -231,15 +289,16 @@ class Downsample(nn.Module): """ Selects every nth element, where n is the index """ + def __init__(self, index): super().__init__() self.index = index def forward(self, x): - return x[::self.index+1] + return x[:: self.index + 1] -def Linear(in_features, out_features, dropout=0., bias=True): +def Linear(in_features, out_features, dropout=0.0, bias=True): """Weight-normalized Linear layer (input: B x T x C)""" m = nn.Linear(in_features, out_features, bias=bias) m.weight.data.normal_(mean=0, std=math.sqrt((1 - dropout) / in_features)) @@ -247,12 +306,12 @@ def Linear(in_features, out_features, dropout=0., bias=True): return nn.utils.weight_norm(m) -def GatedLinear(in_features, out_features, dropout=0., bias=True): +def GatedLinear(in_features, out_features, dropout=0.0, bias=True): """Weight-normalized Linear layer (input: B x T x C) with interspersed GLU units""" return nn.Sequential( - Linear(in_features, out_features*4, dropout, bias), + Linear(in_features, out_features * 4, dropout, bias), nn.GLU(), - Linear(out_features*2, out_features*2, dropout, bias), + Linear(out_features * 2, out_features * 2, dropout, bias), nn.GLU(), - Linear(out_features, out_features, dropout, bias) + Linear(out_features, out_features, dropout, bias), ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamic_convolution.py b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamic_convolution.py new file mode 100644 index 00000000..0121d453 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamic_convolution.py @@ -0,0 +1,310 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.incremental_decoding_utils import with_incremental_state +from fairseq.modules.fairseq_dropout import FairseqDropout + +from .unfold import unfold1d + + +def DynamicConv( + input_size, + kernel_size=1, + padding_l=None, + num_heads=1, + weight_dropout=0.0, + weight_softmax=False, + renorm_padding=False, + bias=False, + conv_bias=False, + query_size=None, + in_proj=False, +): + if torch.cuda.is_available(): + try: + from fairseq.modules.dynamicconv_layer import DynamicconvLayer + + return DynamicconvLayer( + input_size, + kernel_size=kernel_size, + padding_l=padding_l, + num_heads=num_heads, + weight_dropout=weight_dropout, + weight_softmax=weight_softmax, + renorm_padding=renorm_padding, + bias=bias, + conv_bias=conv_bias, + query_size=query_size, + ) + except ImportError as e: + print(e) + return DynamicConv1dTBC( + input_size, + kernel_size=kernel_size, + padding_l=padding_l, + num_heads=num_heads, + weight_dropout=weight_dropout, + weight_softmax=weight_softmax, + renorm_padding=renorm_padding, + bias=bias, + conv_bias=conv_bias, + query_size=query_size, + ) + + +def Linear(in_features, out_features, bias=True): + m = nn.Linear(in_features, out_features, bias) + nn.init.xavier_uniform_(m.weight) + if bias: + nn.init.constant_(m.bias, 0.0) + return m + + +@with_incremental_state +class DynamicConv1dTBC(nn.Module): + """Dynamic lightweight convolution taking T x B x C inputs + Args: + input_size: # of channels of the input + kernel_size: convolution channels + padding_l: padding to the left when using "same" padding + num_heads: number of heads used. The weight is of shape (num_heads, 1, kernel_size) + weight_dropout: the drop rate of the DropConnect to drop the weight + weight_softmax: normalize the weight with softmax before the convolution + renorm_padding: re-normalize the filters to ignore the padded part (only the non-padding parts sum up to 1) + bias: use bias + conv_bias: bias of the convolution + query_size: specified when feeding a different input as the query + in_proj: project the input and generate the filter together + + Shape: + Input: TxBxC, i.e. (timesteps, batch_size, input_size) + Output: TxBxC, i.e. (timesteps, batch_size, input_size) + + Attributes: + weight: the learnable weights of the module of shape + `(num_heads, 1, kernel_size)` + bias: the learnable bias of the module of shape `(input_size)` + """ + + def __init__( + self, + input_size, + kernel_size=1, + padding_l=None, + num_heads=1, + weight_dropout=0.0, + weight_softmax=False, + renorm_padding=False, + bias=False, + conv_bias=False, + query_size=None, + in_proj=False, + ): + super().__init__() + self.input_size = input_size + self.query_size = input_size if query_size is None else query_size + self.kernel_size = kernel_size + self.padding_l = padding_l + self.num_heads = num_heads + self.weight_dropout_module = FairseqDropout( + weight_dropout, module_name=self.__class__.__name__ + ) + self.weight_softmax = weight_softmax + self.renorm_padding = renorm_padding + + if in_proj: + self.weight_linear = Linear( + self.input_size, self.input_size + num_heads * kernel_size * 1 + ) + else: + self.weight_linear = Linear( + self.query_size, num_heads * kernel_size * 1, bias=bias + ) + if conv_bias: + self.conv_bias = nn.Parameter(torch.Tensor(input_size)) + else: + self.conv_bias = None + self.reset_parameters() + + @property + def in_proj(self): + return ( + self.weight_linear.out_features + == self.input_size + self.num_heads * self.kernel_size + ) + + def reset_parameters(self): + self.weight_linear.reset_parameters() + if self.conv_bias is not None: + nn.init.constant_(self.conv_bias, 0.0) + + def forward(self, x, incremental_state=None, query=None, unfold=None): + """Assuming the input, x, of the shape T x B x C and producing an output in the shape T x B x C + args: + x: Input of shape T x B x C, i.e. (timesteps, batch_size, input_size) + incremental_state: A dict to keep the state + unfold: unfold the input or not. If not, we use the matrix trick instead + query: use the specified query to predict the conv filters + """ + unfold = ( + x.size(0) > 512 if unfold is None else unfold + ) # use unfold mode as default for long sequence to save memory + unfold = unfold or (incremental_state is not None) + assert query is None or not self.in_proj + + if query is None: + query = x + if unfold: + output = self._forward_unfolded(x, incremental_state, query) + else: + output = self._forward_expanded(x, incremental_state, query) + + if self.conv_bias is not None: + output = output + self.conv_bias.view(1, 1, -1) + return output + + def _forward_unfolded(self, x, incremental_state, query): + """The conventional implementation of convolutions. + Unfolding the input by having a window shifting to the right.""" + T, B, C = x.size() + K, H = self.kernel_size, self.num_heads + R = C // H + assert R * H == C == self.input_size + + if self.in_proj: + proj = self.weight_linear(x) + x = proj.narrow(2, 0, self.input_size).contiguous() + weight = ( + proj.narrow(2, self.input_size, H * K).contiguous().view(T * B * H, -1) + ) + else: + weight = self.weight_linear(query).view(T * B * H, -1) + + # renorm_padding is only implemented in _forward_expanded + assert not self.renorm_padding or incremental_state is not None + + if incremental_state is not None: + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is None: + input_buffer = x.new() + x_unfold = torch.cat([input_buffer, x.unsqueeze(3)], dim=3) + if self.kernel_size > 1: + self._set_input_buffer( + incremental_state, x_unfold[:, :, :, -self.kernel_size + 1 :] + ) + x_unfold = x_unfold.view(T * B * H, R, -1) + else: + padding_l = self.padding_l + if K > T and padding_l == K - 1: + weight = weight.narrow(1, K - T, T) + K, padding_l = T, T - 1 + # unfold the input: T x B x C --> T' x B x C x K + x_unfold = unfold1d(x, K, padding_l, 0) + x_unfold = x_unfold.view(T * B * H, R, K) + + if self.weight_softmax and not self.renorm_padding: + weight = F.softmax(weight, dim=1) + weight = weight.narrow(1, 0, K) + + if incremental_state is not None: + weight = weight[:, -x_unfold.size(2) :] + K = weight.size(1) + + if self.weight_softmax and self.renorm_padding: + weight = F.softmax(weight, dim=1) + + weight = self.weight_dropout_module(weight, inplace=False) + + output = torch.bmm(x_unfold, weight.unsqueeze(2)) # T*B*H x R x 1 + output = output.view(T, B, C) + return output + + def _forward_expanded(self, x, incremental_stat, query): + """Turn the convolution filters into band matrices and do matrix multiplication. + This is faster when the sequence is short, but less memory efficient. + This is not used in the decoder during inference. + """ + T, B, C = x.size() + K, H = self.kernel_size, self.num_heads + R = C // H + assert R * H == C == self.input_size + if self.in_proj: + proj = self.weight_linear(x) + x = proj.narrow(2, 0, self.input_size).contiguous() + weight = ( + proj.narrow(2, self.input_size, H * K).contiguous().view(T * B * H, -1) + ) + else: + weight = self.weight_linear(query).view(T * B * H, -1) + + if not self.renorm_padding: + if self.weight_softmax: + weight = F.softmax(weight, dim=1) + weight = self.weight_dropout_module(weight, inplace=False) + weight = weight.narrow(1, 0, K).contiguous() + weight = weight.view(T, B * H, K).transpose(0, 1) + + x = x.view(T, B * H, R).transpose(0, 1) + if self.weight_softmax and self.renorm_padding: + # turn the convolution filters into band matrices + weight_expanded = weight.new(B * H, T, T + K - 1).fill_(float("-inf")) + weight_expanded.as_strided( + (B * H, T, K), (T * (T + K - 1), T + K, 1) + ).copy_(weight) + weight_expanded = weight_expanded.narrow(2, self.padding_l, T) + # normalize the weight over valid positions like self-attention + weight_expanded = F.softmax(weight_expanded, dim=2) + weight_expanded = self.weight_dropout_module(weight_expanded, inplace=False) + else: + P = self.padding_l + # For efficiency, we cut the kernel size and reduce the padding when the kernel is larger than the length + if K > T and P == K - 1: + weight = weight.narrow(2, K - T, T) + K, P = T, T - 1 + # turn the convolution filters into band matrices + weight_expanded = weight.new_zeros(B * H, T, T + K - 1, requires_grad=False) + weight_expanded.as_strided( + (B * H, T, K), (T * (T + K - 1), T + K, 1) + ).copy_(weight) + weight_expanded = weight_expanded.narrow(2, P, T) # B*H x T x T + output = torch.bmm(weight_expanded, x) + output = output.transpose(0, 1).contiguous().view(T, B, C) + return output + + def reorder_incremental_state(self, incremental_state, new_order): + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is not None: + input_buffer = input_buffer.index_select(1, new_order) + self._set_input_buffer(incremental_state, input_buffer) + + def _get_input_buffer(self, incremental_state): + return utils.get_incremental_state(self, incremental_state, "input_buffer") + + def _set_input_buffer(self, incremental_state, new_buffer): + return utils.set_incremental_state( + self, incremental_state, "input_buffer", new_buffer + ) + + def extra_repr(self): + s = "{}, kernel_size={}, padding_l={}, num_heads={}, weight_softmax={}, conv_bias={}, renorm_padding={}, in_proj={}".format( + self.input_size, + self.kernel_size, + self.padding_l, + self.num_heads, + self.weight_softmax, + self.conv_bias is not None, + self.renorm_padding, + self.in_proj, + ) + + if self.query_size != self.input_size: + s += ", query_size={}".format(self.query_size) + if self.weight_dropout_module.p > 0.0: + s += ", weight_dropout={}".format(self.weight_dropout_module.p) + return s diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamic_crf_layer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamic_crf_layer.py new file mode 100644 index 00000000..8fcc6b8d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamic_crf_layer.py @@ -0,0 +1,189 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +""" +This file is to re-implemented the low-rank and beam approximation of CRF layer +Proposed by: + +Sun, Zhiqing, et al. +Fast Structured Decoding for Sequence Models +https://arxiv.org/abs/1910.11555 + +The CRF implementation is mainly borrowed from +https://github.com/kmkurn/pytorch-crf/blob/master/torchcrf/__init__.py + +""" + +import numpy as np +import torch +import torch.nn as nn + + +def logsumexp(x, dim=1): + return torch.logsumexp(x.float(), dim=dim).type_as(x) + + +class DynamicCRF(nn.Module): + """Dynamic CRF layer is used to approximate the traditional + Conditional Random Fields (CRF) + $P(y | x) = 1/Z(x) exp(sum_i s(y_i, x) + sum_i t(y_{i-1}, y_i, x))$ + + where in this function, we assume the emition scores (s) are given, + and the transition score is a |V| x |V| matrix $M$ + + in the following two aspects: + (1) it used a low-rank approximation for the transition matrix: + $M = E_1 E_2^T$ + (2) it used a beam to estimate the normalizing factor Z(x) + """ + + def __init__(self, num_embedding, low_rank=32, beam_size=64): + super().__init__() + + self.E1 = nn.Embedding(num_embedding, low_rank) + self.E2 = nn.Embedding(num_embedding, low_rank) + + self.vocb = num_embedding + self.rank = low_rank + self.beam = beam_size + + def extra_repr(self): + return "vocab_size={}, low_rank={}, beam_size={}".format( + self.vocb, self.rank, self.beam + ) + + def forward(self, emissions, targets, masks, beam=None): + """ + Compute the conditional log-likelihood of a sequence of target tokens given emission scores + + Args: + emissions (`~torch.Tensor`): Emission score are usually the unnormalized decoder output + ``(batch_size, seq_len, vocab_size)``. We assume batch-first + targets (`~torch.LongTensor`): Sequence of target token indices + ``(batch_size, seq_len) + masks (`~torch.ByteTensor`): Mask tensor with the same size as targets + + Returns: + `~torch.Tensor`: approximated log-likelihood + """ + numerator = self._compute_score(emissions, targets, masks) + denominator = self._compute_normalizer(emissions, targets, masks, beam) + return numerator - denominator + + def forward_decoder(self, emissions, masks=None, beam=None): + """ + Find the most likely output sequence using Viterbi algorithm. + + Args: + emissions (`~torch.Tensor`): Emission score are usually the unnormalized decoder output + ``(batch_size, seq_len, vocab_size)``. We assume batch-first + masks (`~torch.ByteTensor`): Mask tensor with the same size as targets + + Returns: + `~torch.LongTensor`: decoded sequence from the CRF model + """ + return self._viterbi_decode(emissions, masks, beam) + + def _compute_score(self, emissions, targets, masks=None): + batch_size, seq_len = targets.size() + emission_scores = emissions.gather(2, targets[:, :, None])[:, :, 0] # B x T + transition_scores = (self.E1(targets[:, :-1]) * self.E2(targets[:, 1:])).sum(2) + + scores = emission_scores + scores[:, 1:] += transition_scores + + if masks is not None: + scores = scores * masks.type_as(scores) + return scores.sum(-1) + + def _compute_normalizer(self, emissions, targets=None, masks=None, beam=None): + # HACK: we include "target" which is a hueristic for training + # HACK: we use a beam of tokens to approximate the normalizing factor (which is bad?) + + beam = beam if beam is not None else self.beam + batch_size, seq_len = emissions.size()[:2] + if targets is not None: + _emissions = emissions.scatter(2, targets[:, :, None], np.float("inf")) + beam_targets = _emissions.topk(beam, 2)[1] + beam_emission_scores = emissions.gather(2, beam_targets) + else: + beam_emission_scores, beam_targets = emissions.topk(beam, 2) + beam_transition_score1 = self.E1(beam_targets[:, :-1]) # B x (T-1) x K x D + beam_transition_score2 = self.E2(beam_targets[:, 1:]) # B x (T-1) x K x D + beam_transition_matrix = torch.bmm( + beam_transition_score1.view(-1, beam, self.rank), + beam_transition_score2.view(-1, beam, self.rank).transpose(1, 2), + ) + beam_transition_matrix = beam_transition_matrix.view(batch_size, -1, beam, beam) + + # compute the normalizer in the log-space + score = beam_emission_scores[:, 0] # B x K + for i in range(1, seq_len): + next_score = score[:, :, None] + beam_transition_matrix[:, i - 1] + next_score = logsumexp(next_score, dim=1) + beam_emission_scores[:, i] + + if masks is not None: + score = torch.where(masks[:, i : i + 1], next_score, score) + else: + score = next_score + + # Sum (log-sum-exp) over all possible tags + return logsumexp(score, dim=1) + + def _viterbi_decode(self, emissions, masks=None, beam=None): + # HACK: we use a beam of tokens to approximate the normalizing factor (which is bad?) + + beam = beam if beam is not None else self.beam + batch_size, seq_len = emissions.size()[:2] + beam_emission_scores, beam_targets = emissions.topk(beam, 2) + beam_transition_score1 = self.E1(beam_targets[:, :-1]) # B x (T-1) x K x D + beam_transition_score2 = self.E2(beam_targets[:, 1:]) # B x (T-1) x K x D + beam_transition_matrix = torch.bmm( + beam_transition_score1.view(-1, beam, self.rank), + beam_transition_score2.view(-1, beam, self.rank).transpose(1, 2), + ) + beam_transition_matrix = beam_transition_matrix.view(batch_size, -1, beam, beam) + + traj_tokens, traj_scores = [], [] + finalized_tokens, finalized_scores = [], [] + + # compute the normalizer in the log-space + score = beam_emission_scores[:, 0] # B x K + dummy = ( + torch.arange(beam, device=score.device).expand(*score.size()).contiguous() + ) + + for i in range(1, seq_len): + traj_scores.append(score) + _score = score[:, :, None] + beam_transition_matrix[:, i - 1] + _score, _index = _score.max(dim=1) + _score = _score + beam_emission_scores[:, i] + + if masks is not None: + score = torch.where(masks[:, i : i + 1], _score, score) + index = torch.where(masks[:, i : i + 1], _index, dummy) + else: + score, index = _score, _index + traj_tokens.append(index) + + # now running the back-tracing and find the best + best_score, best_index = score.max(dim=1) + finalized_tokens.append(best_index[:, None]) + finalized_scores.append(best_score[:, None]) + + for idx, scs in zip(reversed(traj_tokens), reversed(traj_scores)): + previous_index = finalized_tokens[-1] + finalized_tokens.append(idx.gather(1, previous_index)) + finalized_scores.append(scs.gather(1, previous_index)) + + finalized_tokens.reverse() + finalized_tokens = torch.cat(finalized_tokens, 1) + finalized_tokens = beam_targets.gather(2, finalized_tokens[:, :, None])[:, :, 0] + + finalized_scores.reverse() + finalized_scores = torch.cat(finalized_scores, 1) + finalized_scores[:, 1:] = finalized_scores[:, 1:] - finalized_scores[:, :-1] + + return finalized_scores, finalized_tokens diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/__init__.py new file mode 100644 index 00000000..22dc6f40 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/__init__.py @@ -0,0 +1,6 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .dynamicconv_layer import DynamicconvLayer # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/cuda_function_gen.py b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/cuda_function_gen.py new file mode 100644 index 00000000..9304f99e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/cuda_function_gen.py @@ -0,0 +1,223 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +def gen_forward(): + + kernels = [3, 5, 7, 15, 31, 63, 127, 255] + blocks = [32, 64, 128, 256] + + head = """ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include "dynamicconv_cuda.cuh" + +std::vector dynamicconv_cuda_forward(at::Tensor input, at::Tensor weight, int padding_l) { + + at::DeviceGuard g(input.device()); + const auto minibatch = input.size(0); + const auto numFeatures = input.size(1); + const auto sequenceLength = input.size(2); + + const auto numHeads = weight.size(1); + const auto filterSize = weight.size(2); + + const auto numFiltersInBlock = numFeatures / numHeads; + const dim3 blocks(minibatch, numFeatures); + + auto output = at::zeros_like(input); + auto stream = at::cuda::getCurrentCUDAStream(); +""" + + switch = """ + switch(filterSize) { +""" + + case_k = """ + case {k}: +""" + + main_block = """ + if (padding_l == {pad}) {{ + AT_DISPATCH_FLOATING_TYPES_AND_HALF(input.scalar_type(), "dynamicconv_forward", ([&] {{ + dynamicconv_forward_kernel<{k}, {b_size}, {pad}, scalar_t> + <<>>( + input.data(), + weight.data(), + minibatch, + sequenceLength, + numFeatures, + numFiltersInBlock, + numHeads, + output.data()); + }})); + }} else +""" + + bad_padding = """ + { + std::cout << "WARNING: Unsupported padding size - skipping forward pass" << std::endl; + } + break;\n +""" + + end = """ + default: + std::cout << "WARNING: Unsupported filter length passed - skipping forward pass" << std::endl; + } + + return {output}; +} +""" + + with open("dynamicconv_cuda_forward.cu", "w") as forward: + forward.write(head) + forward.write(switch) + for k in kernels: + b_size = 32 + for b in blocks: + if b > k: + b_size = b + break + forward.write(case_k.format(k=k)) + for pad in [k // 2, k - 1]: + forward.write(main_block.format(k=k, b_size=b_size, pad=pad)) + forward.write(bad_padding) + forward.write(end) + + +def gen_backward(): + + kernels = [3, 5, 7, 15, 31, 63, 127, 255] + thresh = [512, 512, 512, 512, 512, 380, 256, 256] + min_block = [64, 64, 64, 64, 64, 64, 128, 256] + seqs = [32 * x for x in [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]] + + head = """ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include "dynamicconv_cuda.cuh" + +std::vector dynamicconv_cuda_backward(at::Tensor gradOutput, int padding_l, at::Tensor input, at::Tensor weight) { + + at::DeviceGuard g(input.device()); + const auto minibatch = input.size(0); + const auto numFeatures = input.size(1); + const auto sequenceLength = input.size(2); + + const auto numHeads = weight.size(1); + const auto filterSize = weight.size(2); + + const auto numFiltersInBlock = numFeatures / numHeads; + auto numChunks = 1; + + auto gradInput = at::zeros_like(input); + auto gradWeight = at::zeros_like(weight); + auto stream = at::cuda::getCurrentCUDAStream(); + + dim3 blocks(minibatch, numHeads, numChunks); +""" + + sequence_if = """ + if (sequenceLength < {seq}) {{ + switch(filterSize) {{ +""" + + case_k = """ + case {k}: +""" + + chunks_reset = """ + numChunks = int(ceilf(sequenceLength/float({b_size}))); + blocks = dim3(minibatch, numHeads, numChunks); +""" + + main_block = """ + if (padding_l == {p}) {{ + AT_DISPATCH_FLOATING_TYPES_AND_HALF(gradOutput.scalar_type(), "dynamicconv_backward", ([&] {{ + dynamicconv_backward_kernel<{k}, {b_size}, {p}, scalar_t> + <<>>( + gradOutput.data(), + input.data(), + weight.data(), + minibatch, + sequenceLength, + numFeatures, + numFiltersInBlock, + numHeads, + gradWeight.data(), + gradInput.data()); + }})); + }} else +""" + + bad_padding = """ + { + std::cout << "WARNING: Unsupported padding size - skipping backward pass" << std::endl; + } + break;\n +""" + + bad_filter = """ + default: + std::cout << "WARNING: Unsupported filter length passed - skipping backward pass" << std::endl; + } +""" + + con_else = """ + } else +""" + + final_else = """ + { + switch(filterSize) { +""" + + last_return = """ + } + return {gradInput, gradWeight}; +} +""" + + with open("dynamicconv_cuda_backward.cu", "w") as backward: + backward.write(head) + for seq in seqs: + backward.write(sequence_if.format(seq=seq)) + for k, t, m in zip(kernels, thresh, min_block): + backward.write(case_k.format(k=k)) + if seq <= t: + b_size = seq + else: + b_size = m + backward.write(chunks_reset.format(b_size=b_size)) + for p in [k // 2, k - 1]: + backward.write(main_block.format(k=k, b_size=b_size, p=p)) + backward.write(bad_padding) + backward.write(bad_filter) + backward.write(con_else) + backward.write(final_else) + for k, m in zip(kernels, min_block): + backward.write(case_k.format(k=k)) + backward.write(chunks_reset.format(b_size=m)) + for p in [k // 2, k - 1]: + backward.write(main_block.format(k=k, b_size=m, p=p)) + backward.write(bad_padding) + backward.write(bad_filter) + backward.write(last_return) + + +if __name__ == "__main__": + gen_forward() + gen_backward() diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda.cpp b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda.cpp new file mode 100644 index 00000000..744c363e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda.cpp @@ -0,0 +1,51 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include +#include + +std::vector +dynamicconv_cuda_forward(at::Tensor input, at::Tensor filters, int padding_l); + +std::vector dynamicconv_cuda_backward( + at::Tensor gradOutput, + int padding_l, + at::Tensor input, + at::Tensor filters); + +#define CHECK_CUDA(x) \ + AT_ASSERTM(x.type().is_cuda(), #x " must be a CUDA tensor") +#define CHECK_CONTIGUOUS(x) \ + AT_ASSERTM(x.is_contiguous(), #x " must be contiguous") +#define CHECK_INPUT(x) \ + CHECK_CUDA(x); \ + CHECK_CONTIGUOUS(x) + +std::vector +dynamicconv_forward(at::Tensor input, at::Tensor filters, int padding_l) { + CHECK_INPUT(input); + CHECK_INPUT(filters); + + return dynamicconv_cuda_forward(input, filters, padding_l); +} + +std::vector dynamicconv_backward( + at::Tensor gradOutput, + int padding_l, + at::Tensor input, + at::Tensor filters) { + CHECK_INPUT(gradOutput); + CHECK_INPUT(input); + CHECK_INPUT(filters); + + return dynamicconv_cuda_backward(gradOutput, padding_l, input, filters); +} + +PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) { + m.def("forward", &dynamicconv_forward, "dynamicconv forward (CUDA)"); + m.def("backward", &dynamicconv_backward, "dynamicconv backward (CUDA)"); +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda.cuh b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda.cuh new file mode 100644 index 00000000..44baf21b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda.cuh @@ -0,0 +1,50 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include +#include + +#include +#include +#include + +#include +#include +#include +#include +#include +#include + +#include +#include +#include + +#define SHFL_MASK 0xffffffff + +template +__global__ void dynamicconv_forward_kernel( + const scalar_t* input, + const scalar_t* weight, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + int numHeads, + scalar_t* output); + +template +__global__ void dynamicconv_backward_kernel( + const scalar_t* gradOutput, // B * C * T + const scalar_t* input, // B * C * T + const scalar_t* weight, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + int numHeads, + scalar_t* gradWeight, + scalar_t* gradInput); // B * H * k * T diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda_kernel.cu b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda_kernel.cu new file mode 100644 index 00000000..4630f1e9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_cuda_kernel.cu @@ -0,0 +1,176 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include "../cuda_utils.cu" +#include "dynamicconv_cuda.cuh" +#include "dynamicconv_cuda_backward.cu" +#include "dynamicconv_cuda_forward.cu" + +// FS is filter size and kernels are specialized for filter sizes +template +__global__ void dynamicconv_forward_kernel( + const scalar_t* input, + const scalar_t* weight, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + int numHeads, + scalar_t* output) { + assert(blockDim.x == SB); + + const int tid = threadIdx.x; + const int batchIdx = blockIdx.x; + const int featureIdx = blockIdx.y; + const int head = featureIdx / numFiltersInBlock; + + const int IOOffset = + batchIdx * numFeatures * sequenceLength + featureIdx * sequenceLength; + const scalar_t* inputFeature = &input[IOOffset]; + scalar_t* outputFeature = &output[IOOffset]; + + scalar_t filter[FS]; + + __shared__ scalar_t tempInput[SB + FS]; + zeroSharedMem(tempInput); + + const int numIterations = divUp(sequenceLength, SB); + + for (int i = 0; i < numIterations; ++i) { + __syncthreads(); + const int inputOffset = i * SB; + load_input_to_shared( + inputFeature, + inputOffset, + sequenceLength, + i, + numIterations, + false, + tempInput); + __syncthreads(); + if (inputOffset + tid < sequenceLength) { +#pragma unroll + for (int k = 0; k < FS; ++k) { + const int filterOffset = batchIdx * numHeads * FS * sequenceLength + + head * FS * sequenceLength + k * sequenceLength + i * SB + tid; + filter[k] = weight[filterOffset]; + } + + scalar_t out = scalar_t(0.0); +#pragma unroll + for (int k = 0; k < FS; ++k) { + out += filter[k] * tempInput[tid + k]; + } + + outputFeature[inputOffset + tid] = out; + } + } +} + +template +__global__ void dynamicconv_backward_kernel( + const scalar_t* gradOutput, // B * C * T + const scalar_t* input, // B * C * T + const scalar_t* weight, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + int numHeads, + scalar_t* gradWeight, + scalar_t* gradInput) { // B * H * k * T + + assert(blockDim.x == SB); + + // each block operates on a single batch and filter head + const int tid = threadIdx.x; + const int batchIdx = blockIdx.x; + const int headIdx = blockIdx.y; + const int chunkIdx = blockIdx.z; + + const int numChunks = divUp(sequenceLength, SB); + const int inputOffset = chunkIdx * SB; + + // initialize shared memory for output gradient and input + __shared__ scalar_t tempGradOutput[SB + FS]; + __shared__ scalar_t tempInput[SB + FS]; + const int padding = FS - padding_l - 1; + + zeroSharedMem(tempGradOutput); + zeroSharedMem(tempInput); + + // initialize local filter and weight gradient sum arrays + scalar_t tempGradSum[FS]; + scalar_t bfilter[FS]; + for (int k = 0; k < FS; ++k) { + tempGradSum[k] = scalar_t(0.0); + + int idxOffset = inputOffset + tid + k - padding; + if (idxOffset >= 0 && idxOffset < sequenceLength) { + int bfilterOffset = batchIdx * numHeads * FS * sequenceLength + + headIdx * FS * sequenceLength + (FS - k - 1) * sequenceLength + + idxOffset; + bfilter[k] = weight[bfilterOffset]; + } else { + bfilter[k] = scalar_t(0.0); + } + } + + // iterate over filter block + for (int featureIdx = 0; featureIdx < numFiltersInBlock; ++featureIdx) { + __syncthreads(); + + // load input and output gradient for this channel and chunk + const int IOOffset = batchIdx * numFeatures * sequenceLength + + (headIdx * numFiltersInBlock + featureIdx) * sequenceLength; + const scalar_t* inputFeature = &input[IOOffset]; + const scalar_t* gradOutputFeature = &gradOutput[IOOffset]; + scalar_t* gradInputFeature = &gradInput[IOOffset]; + + load_input_to_shared( + gradOutputFeature, + inputOffset, + sequenceLength, + chunkIdx, + numChunks, + true, + tempGradOutput); + load_input_to_shared( + inputFeature, + inputOffset, + sequenceLength, + chunkIdx, + numChunks, + true, + tempInput); + __syncthreads(); + + // sum input and weight gradients + scalar_t out = scalar_t(0.0); +#pragma unroll + for (int k = 0; k < FS; ++k) { + tempGradSum[k] += tempInput[tid + k] * tempGradOutput[tid + padding]; + out += bfilter[k] * tempGradOutput[tid + k]; + } + + if (inputOffset + tid < sequenceLength) { + gradInputFeature[inputOffset + tid] = out; + } + } + + const int gradOffset = + batchIdx * numHeads * FS * sequenceLength + headIdx * FS * sequenceLength; + scalar_t* gradWeightFeature = &gradWeight[gradOffset]; + + // write weight gradient + if (inputOffset + tid < sequenceLength) { + for (int k = 0; k < FS; ++k) { + const int outputOffset = k * sequenceLength + inputOffset + tid; + gradWeightFeature[outputOffset] = tempGradSum[k]; + } + } +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_layer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_layer.py new file mode 100644 index 00000000..711ed034 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamicconv_layer.py @@ -0,0 +1,227 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import dynamicconv_cuda +import torch +import torch.nn.functional as F +from fairseq import utils +from fairseq.incremental_decoding_utils import with_incremental_state +from fairseq.modules.fairseq_dropout import FairseqDropout +from fairseq.modules.unfold import unfold1d +from torch import nn +from torch.autograd import Function + + +class dynamicconvFunction(Function): + @staticmethod + def forward(ctx, x, weights, padding_l): + ctx.padding_l = padding_l + outputs = dynamicconv_cuda.forward(x, weights, padding_l) + variables = [x, weights] + ctx.save_for_backward(*variables) + return outputs[0] + + @staticmethod + def backward(ctx, grad_output): + outputs = dynamicconv_cuda.backward( + grad_output.contiguous(), ctx.padding_l, *ctx.saved_tensors + ) + grad_input, grad_weights = outputs + return grad_input, grad_weights, None + + +@with_incremental_state +class DynamicconvLayer(nn.Module): + def __init__( + self, + input_size, + kernel_size=1, + padding_l=None, + weight_softmax=False, + num_heads=1, + weight_dropout=0.0, + bias=False, + renorm_padding=False, + conv_bias=False, + query_size=None, + ): + + super(DynamicconvLayer, self).__init__() + self.input_size = input_size + self.query_size = input_size if query_size is None else query_size + self.kernel_size = kernel_size + self.padding_l = padding_l + self.num_heads = num_heads + self.weight_softmax = weight_softmax + self.weight_dropout_module = FairseqDropout( + weight_dropout, module_name=self.__class__.__name__ + ) + self.renorm_padding = renorm_padding + self.bias = bias + + self.weight_linear = nn.Linear(input_size, num_heads * kernel_size, bias) + if conv_bias: + self.conv_bias = nn.Parameter(torch.Tensor(input_size)) + else: + self.conv_bias = None + self.reset_parameters() + + def reset_parameters(self): + nn.init.xavier_uniform_(self.weight_linear.weight) + if self.conv_bias is not None: + nn.init.constant_(self.conv_bias, 0.0) + nn.init.constant_(self.weight_linaer.bias, 0.0) + + def forward(self, x, incremental_state=None, query=None, unfold=None): + + T, B, C = x.size() + K, H = self.kernel_size, self.num_heads + # R = C // H + + # during inference time, incremental BMM is faster + if incremental_state is not None: + unfold = ( + x.size(0) > 512 if unfold is None else unfold + ) # use unfold mode as default for long sequence to save memory + unfold = unfold or (incremental_state is not None) + assert query is None + + if query is None: + query = x + if unfold: + output = self._forward_unfolded(x, incremental_state, query) + else: + output = self._forward_expanded(x, incremental_state, query) + + if self.conv_bias is not None: + output = output + self.conv_bias.view(1, 1, -1) + + return output + + # during training time, use CUDA kernel + else: + weight = self.weight_linear(x).view(T, B, H, K) + if self.weight_softmax: + weight = F.softmax(weight, dim=-1) + if self.weight_dropout_module.p: + weight = self.weight_dropout_module(weight) + + weight = weight.permute(1, 2, 3, 0).contiguous() + self.filters = weight + x = x.permute(1, 2, 0).contiguous() + output = dynamicconvFunction.apply(x, weight, self.padding_l).permute( + 2, 0, 1 + ) + if self.conv_bias is not None: + output = output + self.conv_bias.view(1, 1, -1) + return output + + def reorder_incremental_state(self, incremental_state, new_order): + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is not None: + input_buffer = input_buffer.index_select(1, new_order) + self._set_input_buffer(incremental_state, input_buffer) + + def _get_input_buffer(self, incremental_state): + return utils.get_incremental_state(self, incremental_state, "input_buffer") + + def _set_input_buffer(self, incremental_state, new_buffer): + return utils.set_incremental_state( + self, incremental_state, "input_buffer", new_buffer + ) + + def _forward_unfolded(self, x, incremental_state, query): + """The conventional implementation of convolutions. + Unfolding the input by having a window shifting to the right.""" + T, B, C = x.size() + K, H = self.kernel_size, self.num_heads + R = C // H + assert R * H == C == self.input_size + + weight = self.weight_linear(query).view(T * B * H, -1) + + # renorm_padding is only implemented in _forward_expanded + assert not self.renorm_padding or incremental_state is not None + + if incremental_state is not None: + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is None: + input_buffer = x.new() + x_unfold = torch.cat([input_buffer, x.unsqueeze(3)], dim=3) + if self.kernel_size > 1: + self._set_input_buffer( + incremental_state, x_unfold[:, :, :, -self.kernel_size + 1 :] + ) + x_unfold = x_unfold.view(T * B * H, R, -1) + else: + padding_l = self.padding_l + if K > T and padding_l == K - 1: + weight = weight.narrow(1, K - T, T) + K, padding_l = T, T - 1 + # unfold the input: T x B x C --> T' x B x C x K + x_unfold = unfold1d(x, K, padding_l, 0) + x_unfold = x_unfold.view(T * B * H, R, K) + + if self.weight_softmax and not self.renorm_padding: + weight = F.softmax(weight, dim=1) + weight = weight.narrow(1, 0, K) + + if incremental_state is not None: + weight = weight[:, -x_unfold.size(2) :] + K = weight.size(1) + + if self.weight_softmax and self.renorm_padding: + weight = F.softmax(weight, dim=1) + + weight = self.weight_dropout_module(weight, inplace=False) + + output = torch.bmm(x_unfold, weight.unsqueeze(2)) # T*B*H x R x 1 + output = output.view(T, B, C) + return output + + def _forward_expanded(self, x, incremental_stat, query): + """Turn the convolution filters into band matrices and do matrix multiplication. + This is faster when the sequence is short, but less memory efficient. + This is not used in the decoder during inference. + """ + T, B, C = x.size() + K, H = self.kernel_size, self.num_heads + R = C // H + assert R * H == C == self.input_size + weight = self.weight_linear(query).view(T * B * H, -1) + + if not self.renorm_padding: + if self.weight_softmax: + weight = F.softmax(weight, dim=1) + weight = self.weight_dropout_module(weight, inplace=False) + weight = weight.narrow(1, 0, K).contiguous() + weight = weight.view(T, B * H, K).transpose(0, 1) + + x = x.view(T, B * H, R).transpose(0, 1) + if self.weight_softmax and self.renorm_padding: + # turn the convolution filters into band matrices + weight_expanded = weight.new(B * H, T, T + K - 1).fill_(float("-inf")) + weight_expanded.as_strided( + (B * H, T, K), (T * (T + K - 1), T + K, 1) + ).copy_(weight) + weight_expanded = weight_expanded.narrow(2, self.padding_l, T) + # normalize the weight over valid positions like self-attention + weight_expanded = F.softmax(weight_expanded, dim=2) + weight_expanded = self.weight_dropout_module(weight_expanded, inplace=False) + else: + P = self.padding_l + # For efficiency, we cut the kernel size and reduce the padding when the kernel is larger than the length + if K > T and P == K - 1: + weight = weight.narrow(2, K - T, T) + K, P = T, T - 1 + # turn the convolution filters into band matrices + weight_expanded = weight.new_zeros(B * H, T, T + K - 1, requires_grad=False) + weight_expanded.as_strided( + (B * H, T, K), (T * (T + K - 1), T + K, 1) + ).copy_(weight) + weight_expanded = weight_expanded.narrow(2, P, T) # B*H x T x T + output = torch.bmm(weight_expanded, x) + output = output.transpose(0, 1).contiguous().view(T, B, C) + return output diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamiconv_cpu.cpp b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamiconv_cpu.cpp new file mode 100644 index 00000000..d7e57c85 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/dynamiconv_cpu.cpp @@ -0,0 +1,29 @@ +#include +#include + +std::vector +dynamicconv_cpu_forward(float* input, float* filters, int padding_l); + +std::vector dynamicconv_cpu_backward( + float* gradOutput, + int padding_l, + float* input, + float* filters); + +std::vector +dynamicconv_forward(float* input, float* filters, int padding_l) { + return dynamicconv_cpu_forward(input, filters, padding_l); +} + +std::vector dynamicconv_backward( + float* gradOutput, + int padding_l, + float* input, + float* filters) { + return dynamicconv_cpu_backward(gradOutput, padding_l, input, filters); +} + +PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) { + m.def("forward", &dynamicconv_forward, "dynamicconv forward (CPU)"); + m.def("backward", &dynamicconv_backward, "dynamicconv backward (CPU)"); +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/setup.py b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/setup.py new file mode 100644 index 00000000..6a21f7e2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/dynamicconv_layer/setup.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from setuptools import setup +from torch.utils.cpp_extension import BuildExtension, CUDAExtension + + +setup( + name="dynamicconv_layer", + ext_modules=[ + CUDAExtension( + name="dynamicconv_cuda", + sources=[ + "dynamicconv_cuda.cpp", + "dynamicconv_cuda_kernel.cu", + ], + ), + ], + cmdclass={"build_ext": BuildExtension}, +) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/ema_module.py b/PyTorch/NLP/new-Transformer/fairseq/modules/ema_module.py new file mode 100644 index 00000000..a5b98861 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/ema_module.py @@ -0,0 +1,150 @@ +#!/usr/bin/env python3 + +""" +Used for EMA tracking a given pytorch module. The user is responsible for calling step() +and setting the appropriate decay +""" + +import copy +from dataclasses import dataclass, field +import logging + +import torch + +from fairseq.dataclass import FairseqDataclass + + +@dataclass +class EMAModuleConfig(FairseqDataclass): + ema_decay: float = field( + default=0.9999, metadata={"help": "decay for exponential moving average model"} + ) + ema_fp32: bool = field( + default=False, + metadata={"help": "If true, store EMA model in fp32 even if model is in fp16"}, + ) + + +class EMAModule: + """Exponential Moving Average of Fairseq Models""" + + def __init__(self, model, config: EMAModuleConfig, device=None, skip_keys=None): + """ + @param model model to initialize the EMA with + @param config EMAConfig object with configuration like + ema_decay, ema_update_freq, ema_fp32 + @param device If provided, copy EMA to this device (e.g. gpu). + Otherwise EMA is in the same device as the model. + """ + + self.decay = config.ema_decay + self.model = copy.deepcopy(model) + self.model.requires_grad_(False) + self.config = config + self.skip_keys = skip_keys or set() + self.fp32_params = {} + + if device is not None: + logging.info(f"Copying EMA model to device {device}") + self.model = self.model.to(device=device) + + if self.config.ema_fp32: + self.build_fp32_params() + + self.update_freq_counter = 0 + + def build_fp32_params(self, state_dict=None): + """ + Store a copy of the EMA params in fp32. + If state dict is passed, the EMA params is copied from + the provided state dict. Otherwise, it is copied from the + current EMA model parameters. + """ + if not self.config.ema_fp32: + raise RuntimeError( + "build_fp32_params should not be called if ema_fp32=False. " + "Use ema_fp32=True if this is really intended." + ) + + if state_dict is None: + state_dict = self.model.state_dict() + + def _to_float(t): + return t.float() if torch.is_floating_point(t) else t + + for param_key in state_dict: + if param_key in self.fp32_params: + self.fp32_params[param_key].copy_(state_dict[param_key]) + else: + self.fp32_params[param_key] = _to_float(state_dict[param_key]) + + def restore(self, state_dict, build_fp32_params=False): + """Load data from a model spec into EMA model""" + self.model.load_state_dict(state_dict, strict=False) + if build_fp32_params: + self.build_fp32_params(state_dict) + + def set_decay(self, decay): + self.decay = decay + + def get_decay(self): + return self.decay + + def _step_internal(self, new_model): + """One update of the EMA model based on new model weights""" + decay = self.decay + + ema_state_dict = {} + ema_params = ( + self.fp32_params if self.config.ema_fp32 else self.model.state_dict() + ) + for key, param in new_model.named_parameters(): + if isinstance(param, dict): + continue + try: + ema_param = ema_params[key] + except KeyError: + ema_param = ( + param.float().clone() if param.ndim == 1 else copy.deepcopy(param) + ) + ema_params[key] = ema_param + + if param.shape != ema_param.shape: + raise ValueError( + "incompatible tensor shapes between model param and ema param" + + "{} vs. {}".format(param.shape, ema_param.shape) + ) + + if "version" in key: + # Do not decay a model.version pytorch param + continue + + if key in self.skip_keys or not param.requires_grad: + ema_params[key].copy_(param.to(dtype=ema_param.dtype).data) + ema_param = ema_params[key] + else: + ema_param.mul_(decay) + ema_param.add_(param.data.to(dtype=ema_param.dtype), alpha=1 - decay) + + ema_state_dict[key] = ema_param + + for key, param in new_model.named_buffers(): + ema_state_dict[key] = param + + self.restore(ema_state_dict, build_fp32_params=False) + + @torch.no_grad() + def step(self, new_model): + self._step_internal(new_model) + + def reverse(self, model): + """ + Load the model parameters from EMA model. + Useful for inference or fine-tuning from the EMA model. + """ + d = self.model.state_dict() + if "_ema" in d: + del d["_ema"] + + model.load_state_dict(d, strict=False) + return model diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/espnet_multihead_attention.py b/PyTorch/NLP/new-Transformer/fairseq/modules/espnet_multihead_attention.py new file mode 100644 index 00000000..d319a168 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/espnet_multihead_attention.py @@ -0,0 +1,254 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- + +# Copyright 2019 Shigeki Karita +# Apache 2.0 (http://www.apache.org/licenses/LICENSE-2.0) + +"""Multi-Head Attention layer definition.""" + +import math +import torch +from torch import nn +from fairseq.modules.rotary_positional_embedding import ( + RotaryPositionalEmbedding, + apply_rotary_pos_emb, +) + + +class ESPNETMultiHeadedAttention(nn.Module): + """Multi-Head Attention layer. + Args: + n_head: The number of heads. + n_feat: The number of features. + dropout: Dropout rate. + """ + + def __init__(self, n_feat, n_head, dropout): + """Construct an MultiHeadedAttention object.""" + super(ESPNETMultiHeadedAttention, self).__init__() + assert n_feat % n_head == 0 + # We assume d_v always equals d_k + self.d_k = n_feat // n_head + self.h = n_head + self.linear_q = nn.Linear(n_feat, n_feat) + self.linear_k = nn.Linear(n_feat, n_feat) + self.linear_v = nn.Linear(n_feat, n_feat) + self.linear_out = nn.Linear(n_feat, n_feat) + self.attn = None + self.dropout = nn.Dropout(p=dropout) + + def forward_qkv(self, query, key, value, **kwargs): + """Transform query, key and value. + Args: + query: Query tensor B X T1 X C + key: Key tensor B X T2 X C + value: Value tensor B X T2 X C + Returns: + torch.Tensor: Transformed query tensor B X n_head X T1 X d_k + torch.Tensor: Transformed key tensor B X n_head X T2 X d_k + torch.Tensor: Transformed value tensor B X n_head X T2 X d_k + """ + n_batch = query.size(0) + q = self.linear_q(query).view(n_batch, -1, self.h, self.d_k) + k = self.linear_k(key).view(n_batch, -1, self.h, self.d_k) + v = self.linear_v(value).view(n_batch, -1, self.h, self.d_k) + q = q.transpose(1, 2) # (batch, head, time1, d_k) + k = k.transpose(1, 2) # (batch, head, time2, d_k) + v = v.transpose(1, 2) # (batch, head, time2, d_k) + return q, k, v + + def forward_attention(self, value, scores, mask): + """Compute attention context vector. + Args: + value: Transformed value B X n_head X T2 X d_k. + scores: Attention score B X n_head X T1 X T2 + mask: Mask T2 X B + Returns: + torch.Tensor: Transformed value B X T1 X d_model + weighted by the attention score B X T1 X T2 + """ + n_batch = value.size(0) + if mask is not None: + scores = scores.masked_fill( + mask.unsqueeze(1).unsqueeze(2).to(bool), + float("-inf"), # (batch, head, time1, time2) + ) + self.attn = torch.softmax(scores, dim=-1) # (batch, head, time1, time2) + + else: + self.attn = torch.softmax(scores, dim=-1) # (batch, head, time1, time2) + p_attn = self.dropout(self.attn) + x = torch.matmul(p_attn, value) # (batch, head, time1, d_k) + x = ( + x.transpose(1, 2).contiguous().view(n_batch, -1, self.h * self.d_k) + ) # (batch, time1, d_model) + + return self.linear_out(x) # (batch, time1, d_model) + + def forward(self, query, key, value, key_padding_mask=None, **kwargs): + """Compute scaled dot product attention. + Args: + query (torch.Tensor): Query tensor T X B X C + key (torch.Tensor): Key tensor T X B X C + value (torch.Tensor): Value tensor T X B X C + mask (torch.Tensor): Mask tensor T X B + Returns: + torch.Tensor: Output tensor T X B X D. + """ + query = query.transpose(0, 1) + key = key.transpose(0, 1) + value = value.transpose(0, 1) + + q, k, v = self.forward_qkv(query, key, value) + scores = torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(self.d_k) + scores = self.forward_attention(v, scores, key_padding_mask) + scores = scores.transpose(0, 1) + return scores, None + + +class RelPositionMultiHeadedAttention(ESPNETMultiHeadedAttention): + """Multi-Head Attention layer with relative position encoding. + Paper: https://arxiv.org/abs/1901.02860 + Args: + n_head: The number of heads. + n_feat: The number of features. + dropout: Dropout rate. + zero_triu: Whether to zero the upper triangular part of attention matrix. + """ + + def __init__(self, n_feat, n_head, dropout, zero_triu=False): + """Construct an RelPositionMultiHeadedAttention object.""" + super().__init__(n_feat, n_head, dropout) + self.zero_triu = zero_triu + # linear transformation for positional encoding + self.linear_pos = nn.Linear(n_feat, n_feat, bias=False) + # these two learnable bias are used in matrix c and matrix d + # as described in https://arxiv.org/abs/1901.02860 Section 3.3 + self.pos_bias_u = nn.Parameter(torch.Tensor(self.h, self.d_k)) + self.pos_bias_v = nn.Parameter(torch.Tensor(self.h, self.d_k)) + torch.nn.init.xavier_uniform_(self.pos_bias_u) + torch.nn.init.xavier_uniform_(self.pos_bias_v) + + def rel_shift(self, x): + """Compute relative positional encoding. + Args: + x: Input tensor B X n_head X T X 2T-1 + Returns: + torch.Tensor: Output tensor. + """ + zero_pad = torch.zeros((*x.size()[:3], 1), device=x.device, dtype=x.dtype) + x_padded = torch.cat([zero_pad, x], dim=-1) + + x_padded = x_padded.view(*x.size()[:2], x.size(3) + 1, x.size(2)) + x = x_padded[:, :, 1:].view_as(x)[ + :, :, :, : x.size(-1) // 2 + 1 + ] # only keep the positions from 0 to time2 + + if self.zero_triu: + ones = torch.ones((x.size(2), x.size(3)), device=x.device) + x = x * torch.tril(ones, x.size(3) - x.size(2))[None, None, :, :] + + return x + + def forward(self, query, key, value, pos_emb, key_padding_mask=None, **kwargs): + """Compute scaled dot product attention. + Args: + query: Query tensor T X B X C + key: Key tensor T X B X C + value: Value tensor T X B X C + pos_emb: Positional embedding tensor B X 2T-1 X C + key_padding_mask: Mask tensor T X B + Returns: + torch.Tensor: Output tensor T X B X C. + """ + query = query.transpose(0, 1) + key = key.transpose(0, 1) + value = value.transpose(0, 1) + pos_emb = pos_emb.transpose(0, 1) + q, k, v = self.forward_qkv(query, key, value) + q = q.transpose(1, 2) # (batch, time1, head, d_k) + n_batch_pos = pos_emb.size(0) + p = self.linear_pos(pos_emb).view(n_batch_pos, -1, self.h, self.d_k) + p = p.transpose(1, 2) # (batch, head, 2*time1-1, d_k) + + # (batch, head, time1, d_k) + q_with_bias_u = (q + self.pos_bias_u).transpose(1, 2) + # (batch, head, time1, d_k) + q_with_bias_v = (q + self.pos_bias_v).transpose(1, 2) + + # compute attention score + # first compute matrix a and matrix c + # as described in https://arxiv.org/abs/1901.02860 Section 3.3 + # (batch, head, time1, time2) + matrix_ac = torch.matmul(q_with_bias_u, k.transpose(-2, -1)) + + # compute matrix b and matrix d + # (batch, head, time1, 2*time1-1) + matrix_bd = torch.matmul(q_with_bias_v, p.transpose(-2, -1)) + matrix_bd = self.rel_shift(matrix_bd) + + scores = (matrix_ac + matrix_bd) / math.sqrt( + self.d_k + ) # (batch, head, time1, time2) + + scores = self.forward_attention(v, scores, key_padding_mask) + scores = scores.transpose(0, 1) + return scores, None + + +class RotaryPositionMultiHeadedAttention(ESPNETMultiHeadedAttention): + def __init__( + self, + n_feat, + n_head, + dropout, + precision, + rotary_emd_base=10000, + ): + """Construct an RotaryPositionMultiHeadedAttention object.""" + super().__init__(n_feat, n_head, dropout) + precision = torch.float + self.rotary_ndims = self.d_k # also try self.d_k//2 + if precision == "fp16": + precision = torch.half + + self.rotary_emb = RotaryPositionalEmbedding( + self.rotary_ndims, base=rotary_emd_base, precision=precision + ) + + def forward(self, query, key, value, key_padding_mask=None, **kwargs): + """Compute rotary position attention. + Args: + query: Query tensor T X B X C + key: Key tensor T X B X C + value: Value tensor T X B X C + key_padding_mask: Mask tensor T X B + Returns: + torch.Tensor: Output tensor T X B X D. + Notes: + Assumes self attn + """ + + T, B, C = value.size() + query = query.view(T, B, self.h, self.d_k) + key = key.view(T, B, self.h, self.d_k) + value = value.view(T, B, self.h, self.d_k) + cos, sin = self.rotary_emb(value, seq_len=T) + query, key = apply_rotary_pos_emb( + query, key, cos, sin, offset=0 + ) # offset is based on layer_past + + query = query.view(T, B, self.h * self.d_k) + key = key.view(T, B, self.h * self.d_k) + value = value.view(T, B, self.h * self.d_k) + + # TBD to BTD + query = query.transpose(0, 1) + key = key.transpose(0, 1) + value = value.transpose(0, 1) + + q, k, v = self.forward_qkv(query, key, value) + scores = torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(self.d_k) + scores = self.forward_attention(v, scores, key_padding_mask) + scores = scores.transpose(0, 1) + return scores, None diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/fairseq_dropout.py b/PyTorch/NLP/new-Transformer/fairseq/modules/fairseq_dropout.py new file mode 100644 index 00000000..3cddca77 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/fairseq_dropout.py @@ -0,0 +1,51 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from typing import List, Optional + +import torch.nn as nn +import torch.nn.functional as F + + +logger = logging.getLogger(__name__) + + +class FairseqDropout(nn.Module): + def __init__(self, p, module_name=None): + super().__init__() + self.p = p + self.module_name = module_name + self.apply_during_inference = False + + def forward(self, x, inplace: bool = False): + if self.p > 0 and (self.training or self.apply_during_inference): + return F.dropout(x, p=self.p, training=True, inplace=inplace) + else: + return x + + def make_generation_fast_( + self, + name: str, + retain_dropout: bool = False, + retain_dropout_modules: Optional[List[str]] = None, + **kwargs + ): + if retain_dropout: + if retain_dropout_modules is not None and self.module_name is None: + logger.warning( + "Cannot enable dropout during inference for module {} " + "because module_name was not set".format(name) + ) + elif ( + retain_dropout_modules is None # if None, apply to all modules + or self.module_name in retain_dropout_modules + ): + logger.info( + "Enabling dropout during inference for module: {}".format(name) + ) + self.apply_during_inference = True + else: + logger.info("Disabling dropout for module: {}".format(name)) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_batch_norm.py b/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_batch_norm.py new file mode 100644 index 00000000..c560f338 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_batch_norm.py @@ -0,0 +1,44 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +batch norm done in fp32 (for fp16 training) +""" +import torch +import torch.nn as nn + + +class Fp32BatchNorm(nn.Module): + def __init__(self, sync=False, *args, **kwargs): + super().__init__() + + if sync: + from fairseq.distributed import utils + + if utils.get_global_world_size() == 1: + sync = False + + if sync: + self.bn = nn.SyncBatchNorm(*args, **kwargs) + else: + self.bn = nn.BatchNorm1d(*args, **kwargs) + + self.sync = sync + + def forward(self, input): + if self.bn.running_mean.dtype != torch.float: + if self.sync: + self.bn.running_mean = self.bn.running_mean.float() + self.bn.running_var = self.bn.running_var.float() + if self.bn.affine: + try: + self.bn.weight = self.bn.weight.float() + self.bn.bias = self.bn.bias.float() + except: + self.bn.float() + else: + self.bn.float() + + output = self.bn(input.float()) + return output.type_as(input) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_group_norm.py b/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_group_norm.py new file mode 100644 index 00000000..d03aac02 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_group_norm.py @@ -0,0 +1,25 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Layer norm done in fp32 (for fp16 training) +""" + +import torch.nn as nn +import torch.nn.functional as F + + +class Fp32GroupNorm(nn.GroupNorm): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + + def forward(self, input): + output = F.group_norm( + input.float(), + self.num_groups, + self.weight.float() if self.weight is not None else None, + self.bias.float() if self.bias is not None else None, + self.eps, + ) + return output.type_as(input) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_instance_norm.py b/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_instance_norm.py new file mode 100644 index 00000000..30a54496 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/fp32_instance_norm.py @@ -0,0 +1,35 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Layer norm done in fp32 (for fp16 training) +""" + +import torch.nn as nn +import torch.nn.functional as F + + +class Fp32InstanceNorm(nn.InstanceNorm1d): + def __init__(self, *args, **kwargs): + self.transpose_last = "transpose_last" in kwargs and kwargs["transpose_last"] + if "transpose_last" in kwargs: + del kwargs["transpose_last"] + super().__init__(*args, **kwargs) + + def forward(self, input): + if self.transpose_last: + input = input.transpose(1, 2) + output = F.instance_norm( + input.float(), + running_mean=self.running_mean, + running_var=self.running_var, + weight=self.weight.float() if self.weight is not None else None, + bias=self.bias.float() if self.bias is not None else None, + use_input_stats=self.training or not self.track_running_stats, + momentum=self.momentum, + eps=self.eps, + ) + if self.transpose_last: + output = output.transpose(1, 2) + return output.type_as(input) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/gelu.py b/PyTorch/NLP/new-Transformer/fairseq/modules/gelu.py new file mode 100644 index 00000000..a2f1ecff --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/gelu.py @@ -0,0 +1,25 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +See "Gaussian Error Linear Units (GELUs)" by Dan Hendrycks and Kevin Gimpel with +the corresponding GitHub repo: https://github.com/hendrycks/GELUs +""" + +import math + +import torch +import torch.nn as nn + + +def gelu_accurate(x): + if not hasattr(gelu_accurate, "_a"): + gelu_accurate._a = math.sqrt(2 / math.pi) + return ( + 0.5 * x * (1 + torch.tanh(gelu_accurate._a * (x + 0.044715 * torch.pow(x, 3)))) + ) + + +def gelu(x: torch.Tensor) -> torch.Tensor: + return torch.nn.functional.gelu(x.float()).type_as(x) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/grad_multiply.py b/PyTorch/NLP/new-Transformer/fairseq/modules/grad_multiply.py new file mode 100644 index 00000000..08d15f55 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/grad_multiply.py @@ -0,0 +1,18 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + + +class GradMultiply(torch.autograd.Function): + @staticmethod + def forward(ctx, x, scale): + ctx.scale = scale + res = x.new(x) + return res + + @staticmethod + def backward(ctx, grad): + return grad * ctx.scale, None diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/gumbel_vector_quantizer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/gumbel_vector_quantizer.py new file mode 100644 index 00000000..91655bc5 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/gumbel_vector_quantizer.py @@ -0,0 +1,203 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F + + +class GumbelVectorQuantizer(nn.Module): + def __init__( + self, + dim, + num_vars, + temp, + groups, + combine_groups, + vq_dim, + time_first, + activation=nn.GELU(), + weight_proj_depth=1, + weight_proj_factor=1, + ): + """Vector quantization using gumbel softmax + + Args: + dim: input dimension (channels) + num_vars: number of quantized vectors per group + temp: temperature for training. this should be a tuple of 3 elements: (start, stop, decay factor) + groups: number of groups for vector quantization + combine_groups: whether to use the vectors for all groups + vq_dim: dimensionality of the resulting quantized vector + time_first: if true, expect input in BxTxC format, otherwise in BxCxT + activation: what activation to use (should be a module). this is only used if weight_proj_depth is > 1 + weight_proj_depth: number of layers (with activation in between) to project input before computing logits + weight_proj_factor: this is used only if weight_proj_depth is > 1. scales the inner dimensionality of + projections by this factor + """ + super().__init__() + + self.groups = groups + self.combine_groups = combine_groups + self.input_dim = dim + self.num_vars = num_vars + self.time_first = time_first + + assert ( + vq_dim % groups == 0 + ), f"dim {vq_dim} must be divisible by groups {groups} for concatenation" + + var_dim = vq_dim // groups + num_groups = groups if not combine_groups else 1 + + self.vars = nn.Parameter(torch.FloatTensor(1, num_groups * num_vars, var_dim)) + nn.init.uniform_(self.vars) + + if weight_proj_depth > 1: + + def block(input_dim, output_dim): + return nn.Sequential(nn.Linear(input_dim, output_dim), activation) + + inner_dim = self.input_dim * weight_proj_factor + self.weight_proj = nn.Sequential( + *[ + block(self.input_dim if i == 0 else inner_dim, inner_dim) + for i in range(weight_proj_depth - 1) + ], + nn.Linear(inner_dim, groups * num_vars), + ) + else: + self.weight_proj = nn.Linear(self.input_dim, groups * num_vars) + nn.init.normal_(self.weight_proj.weight, mean=0, std=1) + nn.init.zeros_(self.weight_proj.bias) + + if isinstance(temp, str): + import ast + + temp = ast.literal_eval(temp) + assert len(temp) == 3, f"{temp}, {len(temp)}" + + self.max_temp, self.min_temp, self.temp_decay = temp + self.curr_temp = self.max_temp + self.codebook_indices = None + + def set_num_updates(self, num_updates): + self.curr_temp = max( + self.max_temp * self.temp_decay**num_updates, self.min_temp + ) + + def get_codebook_indices(self): + if self.codebook_indices is None: + from itertools import product + + p = [range(self.num_vars)] * self.groups + inds = list(product(*p)) + self.codebook_indices = torch.tensor( + inds, dtype=torch.long, device=self.vars.device + ).flatten() + + if not self.combine_groups: + self.codebook_indices = self.codebook_indices.view( + self.num_vars**self.groups, -1 + ) + for b in range(1, self.groups): + self.codebook_indices[:, b] += self.num_vars * b + self.codebook_indices = self.codebook_indices.flatten() + return self.codebook_indices + + def codebook(self): + indices = self.get_codebook_indices() + return ( + self.vars.squeeze(0) + .index_select(0, indices) + .view(self.num_vars**self.groups, -1) + ) + + def sample_from_codebook(self, b, n): + indices = self.get_codebook_indices() + indices = indices.view(-1, self.groups) + cb_size = indices.size(0) + assert ( + n < cb_size + ), f"sample size {n} is greater than size of codebook {cb_size}" + sample_idx = torch.randint(low=0, high=cb_size, size=(b * n,)) + indices = indices[sample_idx] + + z = self.vars.squeeze(0).index_select(0, indices.flatten()).view(b, n, -1) + return z + + def to_codebook_index(self, indices): + res = indices.new_full(indices.shape[:-1], 0) + for i in range(self.groups): + exponent = self.groups - i - 1 + res += indices[..., i] * (self.num_vars**exponent) + return res + + def forward_idx(self, x): + res = self.forward(x, produce_targets=True) + return res["x"], res["targets"] + + def forward(self, x, produce_targets=False): + + result = {"num_vars": self.num_vars * self.groups} + + if not self.time_first: + x = x.transpose(1, 2) + + bsz, tsz, fsz = x.shape + x = x.reshape(-1, fsz) + x = self.weight_proj(x) + x = x.view(bsz * tsz * self.groups, -1) + + _, k = x.max(-1) + hard_x = ( + x.new_zeros(*x.shape) + .scatter_(-1, k.view(-1, 1), 1.0) + .view(bsz * tsz, self.groups, -1) + ) + hard_probs = torch.mean(hard_x.float(), dim=0) + result["code_perplexity"] = torch.exp( + -torch.sum(hard_probs * torch.log(hard_probs + 1e-7), dim=-1) + ).sum() + + avg_probs = torch.softmax( + x.view(bsz * tsz, self.groups, -1).float(), dim=-1 + ).mean(dim=0) + result["prob_perplexity"] = torch.exp( + -torch.sum(avg_probs * torch.log(avg_probs + 1e-7), dim=-1) + ).sum() + + result["temp"] = self.curr_temp + + if self.training: + x = F.gumbel_softmax(x.float(), tau=self.curr_temp, hard=True).type_as(x) + else: + x = hard_x + + x = x.view(bsz * tsz, -1) + + vars = self.vars + if self.combine_groups: + vars = vars.repeat(1, self.groups, 1) + + if produce_targets: + result["targets"] = ( + x.view(bsz * tsz * self.groups, -1) + .argmax(dim=-1) + .view(bsz, tsz, self.groups) + .detach() + ) + + x = x.unsqueeze(-1) * vars + x = x.view(bsz * tsz, self.groups, self.num_vars, -1) + x = x.sum(-2) + x = x.view(bsz, tsz, -1) + + if not self.time_first: + x = x.transpose(1, 2) # BTC -> BCT + + result["x"] = x + + return result diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/kmeans_attention.py b/PyTorch/NLP/new-Transformer/fairseq/modules/kmeans_attention.py new file mode 100644 index 00000000..0088d1eb --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/kmeans_attention.py @@ -0,0 +1,744 @@ +import math +from functools import reduce, wraps +from inspect import isfunction +from operator import mul + +import torch +import torch.nn as nn +import torch.nn.functional as F +from aml.multimodal_video.utils.einops.lib import rearrange, repeat +from aml.multimodal_video.utils.einops.lib.layers.torch import Rearrange + +from fairseq.modules.local_attention import LocalAttention + +# constants + +TOKEN_SELF_ATTN_VALUE = -5e4 +KMEAN_INIT_ITERS = 10 + +# helper functions + + +def exists(val): + return val is not None + + +def identity(x, *args, **kwargs): + return x + + +def default(x, d): + if not exists(x): + return d if not isfunction(d) else d() + return x + + +def cast_tuple(x): + return x if isinstance(x, tuple) else (x,) + + +def cache_fn(f): + cache = None + + @wraps(f) + def cached_fn(*args, **kwargs): + nonlocal cache + if exists(cache): + return cache + cache = f(*args, **kwargs) + return cache + + return cached_fn + + +def to(t): + return {"device": t.device, "dtype": t.dtype} + + +def find_modules(nn_module, type): + return [module for module in nn_module.modules() if isinstance(module, type)] + + +def is_empty(t): + return t.nelement() == 0 + + +def max_neg_value(tensor): + return -torch.finfo(tensor.dtype).max + + +def batched_index_select(values, indices): + last_dim = values.shape[-1] + return values.gather(2, expand_dim(indices, -1, last_dim)) + + +def merge_dims(ind_from, ind_to, tensor): + shape = list(tensor.shape) + arr_slice = slice(ind_from, ind_to + 1) + shape[arr_slice] = [reduce(mul, shape[arr_slice])] + return tensor.reshape(*shape) + + +def expand_dim(t, dim, k): + t = t.unsqueeze(dim) + expand_shape = [-1] * len(t.shape) + expand_shape[dim] = k + return t.expand(*expand_shape) + + +def scatter_mean(src, t, index, dim, eps=1e-5): + numer = src.scatter_add(dim, index, t) + denom = src.scatter_add(dim, index, torch.ones_like(t)) + return numer / (denom + eps) + + +def split_at_index(dim, index, t): + pre_slices = (slice(None),) * dim + l = (*pre_slices, slice(None, index)) + r = (*pre_slices, slice(index, None)) + return t[l], t[r] + + +def reshape_dim(t, dim, split_dims): + shape = list(t.shape) + num_dims = len(shape) + dim = (dim + num_dims) % num_dims + shape[dim : dim + 1] = split_dims + return t.reshape(shape) + + +def ema(old, new, decay): + if not exists(old): + return new + return old * decay + new * (1 - decay) + + +def ema_inplace(moving_avg, new, decay): + if is_empty(moving_avg): + moving_avg.data.copy_(new) + return + moving_avg.data.mul_(decay).add_(new, alpha=(1 - decay)) + + +# helper classes + + +def map_first_tuple_or_el(x, fn): + if isinstance(x, tuple): + return (fn(x[0]),) + x[1:] + return fn(x) + + +class Chunk(nn.Module): + def __init__(self, chunks, fn, along_dim=-1): + super().__init__() + self.dim = along_dim + self.chunks = chunks + self.fn = fn + + def forward(self, x, **kwargs): + if self.chunks <= 1: + return self.fn(x, **kwargs) + chunks = x.chunk(self.chunks, dim=self.dim) + return torch.cat([self.fn(c, **kwargs) for c in chunks], dim=self.dim) + + +class PreNorm(nn.ModuleList): + def __init__(self, norm_class, dim, fn): + super().__init__() + self.norm = norm_class(dim) + self.fn = fn + + def forward(self, x, **kwargs): + x = self.norm(x) + return self.fn(x, **kwargs) + + +class ReZero(nn.Module): + def __init__(self, fn): + super().__init__() + self.residual_weight = nn.Parameter(torch.zeros(1)) + self.fn = fn + + def forward(self, x, **kwargs): + x = self.fn(x, **kwargs) + return map_first_tuple_or_el(x, lambda t: t * self.residual_weight) + + +class ScaleNorm(nn.Module): + def __init__(self, dim, eps=1e-5): + super().__init__() + self.g = nn.Parameter(torch.ones(1)) + self.eps = eps + + def forward(self, x): + def norm(t): + n = torch.norm(t, dim=-1, keepdim=True).clamp(min=self.eps) + return t / n * self.g + + return map_first_tuple_or_el(x, norm) + + +class ProjectInOut(nn.Module): + def __init__(self, fn, dim_in, dim_out, project_out=True): + super().__init__() + self.fn = fn + self.project_in = nn.Linear(dim_in, dim_out) + self.project_out = nn.Linear(dim_out, dim_in) if project_out else identity + + def forward(self, x, **kwargs): + x = self.project_in(x) + x, loss = self.fn(x, **kwargs) + x = self.project_out(x) + return x, loss + + +class MatrixMultiply(nn.Module): + def __init__(self, tensor, transpose=False): + super().__init__() + self.tensor = tensor + self.transpose = transpose + + def forward(self, x): + tensor = self.tensor + if self.transpose: + tensor = tensor.t() + return x @ tensor + + +# positional embeddings + + +class DepthWiseConv1d(nn.Module): + def __init__(self, dim_in, dim_out, kernel_size, stride=1, bias=True, causal=False): + super().__init__() + self.padding = ( + ((kernel_size - 1), 0) if causal else (kernel_size // 2, kernel_size // 2) + ) + + self.net = nn.Sequential( + nn.Conv1d( + dim_in, + dim_in, + kernel_size=kernel_size, + groups=dim_in, + stride=stride, + bias=bias, + ), + nn.Conv1d(dim_in, dim_out, 1, bias=bias), + ) + + def forward(self, x): + x = F.pad(x, self.padding, value=0.0) + return self.net(x) + + +class FixedPositionalEmbedding(nn.Module): + def __init__(self, dim, max_seq_len): + super().__init__() + inv_freq = 1.0 / (10000 ** (torch.arange(0, dim, 2).float() / dim)) + position = torch.arange(0, max_seq_len, dtype=torch.float) + sinusoid_inp = torch.einsum("i,j->ij", position, inv_freq) + emb = torch.cat((sinusoid_inp.sin(), sinusoid_inp.cos()), dim=-1) + self.register_buffer("emb", emb) + + def forward(self, x): + return self.emb[None, : x.shape[1], :].to(x) + + +def rotate_every_two(x): + x = rearrange(x, "... (d j) -> ... d j", j=2) + x1, x2 = x.unbind(dim=-1) + x = torch.stack((-x2, x1), dim=-1) + return rearrange(x, "... d j -> ... (d j)") + + +def apply_rotary_pos_emb(q, k, sinu_pos): + sinu_pos = rearrange(sinu_pos, "() n (j d) -> n j d", j=2) + sin, cos = sinu_pos.unbind(dim=-2) + sin, cos = map(lambda t: repeat(t, "b n -> b (n j)", j=2), (sin, cos)) + q, k = map(lambda t: (t * cos) + (rotate_every_two(t) * sin), (q, k)) + return q, k + + +# kmeans related function and class + + +def update_kmeans_on_backwards(module): + module.kmean_modules = find_modules(module, Kmeans) + + def hook(_, grad_in, grad_out): + for m in module.kmean_modules: + m.update() + + return module.register_backward_hook(hook) + + +def similarity(x, means): + return torch.einsum("bhld,hcd->bhlc", x, means) + + +def dists_and_buckets(x, means): + dists = similarity(x, means) + _, buckets = torch.max(dists, dim=-1) + return dists, buckets + + +def batched_bincount(index, num_classes, dim=-1): + shape = list(index.shape) + shape[dim] = num_classes + out = index.new_zeros(shape) + out.scatter_add_(dim, index, torch.ones_like(index, dtype=index.dtype)) + return out + + +def kmeans_iter(x, means, buckets=None): + b, h, _, d, dtype, num_clusters = *x.shape, x.dtype, means.shape[1] + + if not exists(buckets): + _, buckets = dists_and_buckets(x, means) + + bins = batched_bincount(buckets, num_clusters).sum(0, keepdim=True) + zero_mask = bins.long() == 0 + + means_ = buckets.new_zeros(b, h, num_clusters, d, dtype=dtype) + means_.scatter_add_(-2, expand_dim(buckets, -1, d), x) + means_ = F.normalize(means_.sum(0, keepdim=True), dim=-1).type(dtype) + + means = torch.where(zero_mask.unsqueeze(-1), means, means_) + means = means.squeeze(0) + return means + + +def distribution(dists, window_size): + _, topk_indices = dists.topk(k=window_size, dim=-2) + indices = topk_indices.transpose(-2, -1) + return indices.reshape(*indices.size()[:2], -1) + + +class Kmeans(nn.Module): + def __init__( + self, num_heads, head_dim, num_clusters, ema_decay=0.999, commitment=1e-4 + ): + super().__init__() + self.commitment = commitment + self.ema_decay = ema_decay + + self.register_buffer("means", torch.randn(num_heads, num_clusters, head_dim)) + self.register_buffer("initted", torch.tensor(False)) + self.num_new_means = 0 + self.new_means = None + + @torch.no_grad() + def init(self, x): + if self.initted: + return + _, h, _, d, device, _ = *x.shape, x.device, x.dtype + + num_clusters = self.means.shape[1] + + means = x.transpose(0, 1).contiguous().view(h, -1, d) + num_samples = means.shape[1] + + if num_samples >= num_clusters: + indices = torch.randperm(num_samples, device=device)[:num_clusters] + else: + indices = torch.randint(0, num_samples, (num_clusters,), device=device) + + means = means[:, indices] + + for _ in range(KMEAN_INIT_ITERS): + means = kmeans_iter(x, means) + + self.num_new_means = 0 + self.means.data.copy_(means) + self.initted.data.copy_(torch.tensor(True)) + + @torch.no_grad() + def update(self, new_means=None): + new_means = default(new_means, self.new_means) + assert exists(new_means), "new kmeans has not been supplied" + ema_inplace(self.means, new_means, self.ema_decay) + + del self.new_means + self.new_means = None + self.num_new_means = 0 + + def forward(self, x, update_means=False): + self.init(x) + + b, dtype = x.shape[0], x.dtype + means = self.means.type(dtype) + x = F.normalize(x, 2, dim=-1).type(dtype) + + with torch.no_grad(): + dists, buckets = dists_and_buckets(x, means) + + routed_means = batched_index_select(expand_dim(means, 0, b), buckets) + loss = F.mse_loss(x, routed_means) * self.commitment + + if update_means: + with torch.no_grad(): + means = kmeans_iter(x, means, buckets) + self.new_means = ema( + self.new_means, means, self.num_new_means / (self.num_new_means + 1) + ) + self.num_new_means += 1 + + return dists, loss + + +# kmeans attention class + + +class KmeansAttention(nn.Module): + def __init__( + self, + num_clusters, + window_size, + num_heads, + head_dim, + causal=False, + dropout=0.0, + ema_decay=0.999, + commitment=1e-4, + context_window_size=None, + receives_context=False, + num_mem_kv=0, + shared_qk=False, + ): + super().__init__() + self.num_heads = num_heads + self.num_clusters = num_clusters + self.head_dim = head_dim + + self.window_size = window_size + self.context_window_size = default(context_window_size, window_size) + self.causal = causal + + self.shared_qk = shared_qk + self.receives_context = receives_context + self.kmeans = Kmeans(num_heads, head_dim, num_clusters, ema_decay, commitment) + self.dropout = nn.Dropout(dropout) + + self.num_mem_kv = max(num_mem_kv, 1 if causal and not shared_qk else 0) + self.mem_key = nn.Parameter( + torch.randn(num_heads, num_clusters, self.num_mem_kv, head_dim) + ) + self.mem_value = nn.Parameter( + torch.randn(num_heads, num_clusters, self.num_mem_kv, head_dim) + ) + + def forward(self, q, k, v, query_mask=None, key_mask=None, **kwargs): + b, h, t, d, kv_t, wsz, c_wsz, nc, device, dtype = ( + *q.shape, + k.shape[2], + self.window_size, + self.context_window_size, + self.num_clusters, + q.device, + q.dtype, + ) + is_reverse = kwargs.pop("_reverse", False) + + out = torch.zeros_like(q, dtype=dtype) + + update_kmeans = self.training and not is_reverse + + key_mask = ( + default(key_mask, query_mask) if not self.receives_context else key_mask + ) + kv_wsz = wsz if not self.receives_context else c_wsz + + wsz = min(wsz, t) + kv_wsz = min(kv_wsz, kv_t) + + if not self.shared_qk or self.receives_context: + dists, aux_loss = self.kmeans(torch.cat((q, k), dim=2), update_kmeans) + q_dists, k_dists = split_at_index(2, t, dists) + indices = distribution(q_dists, wsz) + kv_indices = distribution(k_dists, kv_wsz) + else: + dists, aux_loss = self.kmeans(q, update_kmeans) + k = F.normalize(k, dim=-1).to(q) + indices = distribution(dists, wsz) + kv_indices = indices + + q = batched_index_select(q, indices) + k = batched_index_select(k, kv_indices) + v = batched_index_select(v, kv_indices) + + reshape_with_window = lambda x: x.reshape(b, h, nc, -1, d) + q, k, v = map(reshape_with_window, (q, k, v)) + + m_k, m_v = map( + lambda x: expand_dim(x, 0, b).to(q), (self.mem_key, self.mem_value) + ) + k, v = map(lambda x: torch.cat(x, dim=3), ((m_k, k), (m_v, v))) + + dots = torch.einsum("bhnid,bhnjd->bhnij", q, k) * (d**-0.5) + + mask_value = max_neg_value(dots) + + if exists(query_mask) or exists(key_mask): + query_mask = default( + query_mask, lambda: torch.ones((b, t), device=device).bool() + ) + key_mask = default( + key_mask, lambda: torch.ones((b, kv_t), device=device).bool() + ) + + q_mask = expand_dim(query_mask, 1, h).gather(2, indices) + kv_mask = expand_dim(key_mask, 1, h).gather(2, kv_indices) + q_mask, kv_mask = map(lambda t: t.reshape(b, h, nc, -1), (q_mask, kv_mask)) + mask = q_mask[:, :, :, :, None] * kv_mask[:, :, :, None, :] + mask = F.pad(mask, (self.num_mem_kv, 0), value=1) + dots.masked_fill_(~mask, mask_value) + del mask + + if self.causal: + q_mask, kv_mask = map( + lambda t: t.reshape(b, h, nc, -1), (indices, kv_indices) + ) + mask = q_mask[:, :, :, :, None] >= kv_mask[:, :, :, None, :] + mask = F.pad(mask, (self.num_mem_kv, 0), value=1) + dots.masked_fill_(~mask, mask_value) + del mask + + if self.shared_qk: + q_mask, kv_mask = map( + lambda t: t.reshape(b, h, nc, -1), (indices, kv_indices) + ) + mask = q_mask[:, :, :, :, None] == kv_mask[:, :, :, None, :] + mask = F.pad(mask, (self.num_mem_kv, 0), value=0) + dots.masked_fill_(mask, TOKEN_SELF_ATTN_VALUE) + del mask + + dots = dots.softmax(dim=-1) + dots = self.dropout(dots) + + bo = torch.einsum("bhcij,bhcjd->bhcid", dots, v) + so = torch.reshape(bo, (b, h, -1, bo.shape[-1])).type(dtype) + out = scatter_mean(out, so, indices.unsqueeze(-1).expand_as(so), -2) + return out, aux_loss + + +# feedforward + + +class GELU_(nn.Module): + def forward(self, x): + return ( + 0.5 + * x + * ( + 1 + + torch.tanh(math.sqrt(2 / math.pi) * (x + 0.044715 * torch.pow(x, 3))) + ) + ) + + +GELU = nn.GELU if hasattr(nn, "GELU") else GELU_ + + +class FeedForward(nn.Module): + def __init__(self, dim, mult=4, dropout=0.0, activation=None, glu=False): + super().__init__() + activation = default(activation, GELU) + + self.glu = glu + self.w1 = nn.Linear(dim, dim * mult * (2 if glu else 1)) + self.act = activation() + self.dropout = nn.Dropout(dropout) + self.w2 = nn.Linear(dim * mult, dim) + + def forward(self, x, **kwargs): + if not self.glu: + x = self.w1(x) + x = self.act(x) + else: + x, v = self.w1(x).chunk(2, dim=-1) + x = self.act(x) * v + + x = self.dropout(x) + x = self.w2(x) + return x + + +# self attention + + +class SelfAttention(nn.Module): + def __init__( + self, + dim, + max_seq_len, + heads, + local_attn_heads, + window_size, + dim_head=None, + local_attn_window_size=None, + local_attn_radius_blocks=1, + causal=False, + attn_dropout=0.0, + dropout=0.0, + kmeans_ema_decay=0.999, + commitment_factor=1e-4, + receives_context=False, + context_window_size=None, + rel_pos_emb=True, + num_mem_kv=0, + shared_qk=False, + conv_query_kernel=9, + ): + super().__init__() + assert ( + dim_head or (dim % heads) == 0 + ), "hidden dimension must be divisible by number of heads" + assert ( + max_seq_len % window_size + ) == 0, "maximum sequence length must be divisible by the target window size" + assert ( + local_attn_heads <= heads + ), "number of local attention heads must be less than total heads" + assert not ( + receives_context and local_attn_heads > 0 + ), "local attention cannot be used for self attention with context" + assert not ( + receives_context and causal + ), "contextual attention layer cannot be causal" + + local_attn_window_size = default(local_attn_window_size, window_size) + context_window_size = default(context_window_size, window_size) + + self.shared_qk = shared_qk + self.receives_context = receives_context + self.heads = heads + self.local_attn_heads = local_attn_heads + self.global_attn_heads = heads - local_attn_heads + + self.causal = causal + self.window_size = window_size + + dim_head = default(dim_head, dim // heads) + dim_heads = dim_head * heads + self.dim_head = dim_head + + num_clusters = max_seq_len // window_size + + # local + + local_dim_heads = dim_head * self.local_attn_heads + + if self.local_attn_heads > 0: + rel_pos_emb_config = (dim_head, local_attn_heads) if rel_pos_emb else None + self.local_attn = LocalAttention( + dim=dim_head, + window_size=local_attn_window_size, + causal=causal, + dropout=attn_dropout, + rel_pos_emb_config=rel_pos_emb_config, + look_backward=local_attn_radius_blocks, + look_forward=0 if causal else local_attn_radius_blocks, + ) + self.local_to_qkv = nn.Linear(dim, 3 * local_dim_heads) + + # global + + global_dim_heads = dim_head * self.global_attn_heads + + if self.global_attn_heads > 0: + self.global_attn = KmeansAttention( + num_clusters, + window_size, + self.global_attn_heads, + dim_head, + causal=causal, + dropout=attn_dropout, + ema_decay=kmeans_ema_decay, + commitment=commitment_factor, + receives_context=receives_context, + num_mem_kv=num_mem_kv, + shared_qk=shared_qk, + ) + + self.to_q = nn.Sequential( + Rearrange("b n c -> b c n"), + DepthWiseConv1d(dim, global_dim_heads, conv_query_kernel, causal=causal), + Rearrange("b c n -> b n c"), + ) + + self.to_v = nn.Linear(dim, global_dim_heads, bias=False) + + if not self.shared_qk: + self.to_k = nn.Linear(dim, global_dim_heads, bias=False) + + # out + + self.to_out = nn.Linear(dim_heads, dim, bias=False) + self.dropout = nn.Dropout(dropout) + + def forward( + self, + query, + key, + value, + context=None, + key_padding_mask=None, + context_mask=None, + pos_emb=None, + **kwargs + ): + assert not ( + self.receives_context and not exists(context) + ), "context must be passed if self attention is set to receive context" + input_mask = key_padding_mask + x = query.transpose(0, 1) + b, t, _, h, dh = *x.shape, self.heads, self.dim_head + has_local, has_global = map( + lambda x: x > 0, (self.local_attn_heads, self.global_attn_heads) + ) + + split_heads = ( + lambda v: reshape_dim(v, -1, (-1, dh)).transpose(1, 2).contiguous() + ) + + if has_local: + local_qkv = self.local_to_qkv(x).chunk(3, dim=-1) + lq, lk, lv = map(split_heads, local_qkv) + + if has_global: + kv_input = x if not self.receives_context else context + + q, v = self.to_q(x), self.to_v(kv_input) + + if not self.shared_qk: + k = self.to_k(kv_input) + else: + k = self.to_q(kv_input) if self.receives_context else q + + q, k, v = map(split_heads, (q, k, v)) + + out = [] + total_loss = torch.tensor(0.0, requires_grad=True, **to(x)) + + if has_local: + local_out = self.local_attn(lq, lk, lv, input_mask=input_mask) + out.append(local_out) + + if has_global: + if not self.receives_context and exists(pos_emb): + q, k = apply_rotary_pos_emb(q, k, pos_emb) + + global_out, loss = self.global_attn( + q, k, v, query_mask=input_mask, key_mask=context_mask + ) + total_loss = total_loss + loss + + out.append(global_out) + + out = torch.cat(out, dim=1) + out = out.reshape(b, h, t, -1).transpose(1, 2).reshape(b, t, -1) + out = self.dropout(out.transpose(0, 1)) + # out = self.to_out(out) + return out, total_loss diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/kmeans_vector_quantizer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/kmeans_vector_quantizer.py new file mode 100644 index 00000000..040db1e8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/kmeans_vector_quantizer.py @@ -0,0 +1,127 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +from fairseq.modules import Fp32GroupNorm + + +class KmeansVectorQuantizer(nn.Module): + def __init__( + self, dim, num_vars, groups, combine_groups, vq_dim, time_first, gamma=0.25 + ): + """Vector quantization using straight pass-through estimator (i.e. kmeans) + + Args: + dim: input dimension (channels) + num_vars: number of quantized vectors per group + groups: number of groups for vector quantization + combine_groups: whether to use the vectors for all groups + vq_dim: dimensionality of the resulting quantized vector + time_first: if true, expect input in BxTxC format, otherwise in BxCxT + gamma: commitment loss coefficient + """ + super().__init__() + + self.groups = groups + self.combine_groups = combine_groups + self.input_dim = dim + self.num_vars = num_vars + self.vq_dim = vq_dim + self.time_first = time_first + + assert ( + vq_dim % groups == 0 + ), f"dim {vq_dim} must be divisible by groups {groups} for concatenation" + + self.var_dim = vq_dim // groups + num_groups = groups if not combine_groups else 1 + + self.embedding = nn.Parameter( + 0.01 * torch.randn(num_vars, num_groups, self.var_dim) + ) + self.projection = nn.Sequential( + nn.Conv1d(dim, dim, kernel_size=1, groups=groups, bias=False), + Fp32GroupNorm(groups, dim), + ) + self.gamma = gamma + self.mse_mean = nn.MSELoss(reduction="mean") + + def _pass_grad(self, x, y): + """Manually set gradient for backward pass. + for y = f(x), ensure that during the backward pass, + dL/dy = dL/dx regardless of f(x). + Returns: + y, with the gradient forced to be dL/dy = dL/dx. + """ + + return y.detach() + (x - x.detach()) + + @property + def expand_embedding(self): + if self.combine_groups: + return self.embedding.expand(self.num_vars, self.groups, self.var_dim) + return self.embedding + + def forward_idx(self, x): + res = self.forward(x, produce_targets=True) + return res["x"], res["targets"] + + def forward(self, x, produce_targets=False): + + result = {"num_vars": self.num_vars} + + if self.time_first: + x = x.transpose(1, 2) + + bsz, fsz, tsz = x.shape + + ze = self.projection(x) + ze_ = ze.view(bsz, self.groups, self.var_dim, tsz).permute(0, 3, 1, 2) + d = ( + (ze_.unsqueeze(0) - self.expand_embedding.unsqueeze(1).unsqueeze(1)) + .view(self.num_vars, bsz, tsz, self.groups, -1) + .norm(dim=-1, p=2) + ) + idx = d.argmin(dim=0) + zq = ( + torch.stack( + [ + self.expand_embedding[idx[..., group], group] + for group in range(self.groups) + ], + dim=-2, + ) + .view(bsz, tsz, self.groups * self.var_dim) + .permute(0, 2, 1) + ) + assert ze.shape == zq.shape, (ze.shape, zq.shape) + x = self._pass_grad(ze, zq) + + hard_x = ( + idx.new_zeros(bsz * tsz * self.groups, self.num_vars) + .scatter_(-1, idx.view(-1, 1), 1.0) + .view(bsz * tsz, self.groups, -1) + ) + hard_probs = torch.mean(hard_x.float(), dim=0) + result["code_perplexity"] = torch.exp( + -torch.sum(hard_probs * torch.log(hard_probs + 1e-7), dim=-1) + ).sum() + + if produce_targets: + result["targets"] = idx + + if self.time_first: + x = x.transpose(1, 2) # BCT -> BTC + result["x"] = x + + ze = ze.float() + zq = zq.float() + latent_loss = self.mse_mean(zq, ze.detach()) + commitment_loss = self.mse_mean(ze, zq.detach()) + + result["kmeans_loss"] = latent_loss + self.gamma * commitment_loss + + return result diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/layer_drop.py b/PyTorch/NLP/new-Transformer/fairseq/modules/layer_drop.py new file mode 100644 index 00000000..8961d8bc --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/layer_drop.py @@ -0,0 +1,44 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +LayerDrop as described in https://arxiv.org/abs/1909.11556. +""" + +import torch +import torch.nn as nn + + +class LayerDropModuleList(nn.ModuleList): + """ + A LayerDrop implementation based on :class:`torch.nn.ModuleList`. + + We refresh the choice of which layers to drop every time we iterate + over the LayerDropModuleList instance. During evaluation we always + iterate over all layers. + + Usage:: + + layers = LayerDropList(p=0.5, modules=[layer1, layer2, layer3]) + for layer in layers: # this might iterate over layers 1 and 3 + x = layer(x) + for layer in layers: # this might iterate over all layers + x = layer(x) + for layer in layers: # this might not iterate over any layers + x = layer(x) + + Args: + p (float): probability of dropping out each layer + modules (iterable, optional): an iterable of modules to add + """ + + def __init__(self, p, modules=None): + super().__init__(modules) + self.p = p + + def __iter__(self): + dropout_probs = torch.empty(len(self)).uniform_() + for i, m in enumerate(super().__iter__()): + if not self.training or (dropout_probs[i] > self.p): + yield m diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/layer_norm.py b/PyTorch/NLP/new-Transformer/fairseq/modules/layer_norm.py new file mode 100644 index 00000000..0b276ce0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/layer_norm.py @@ -0,0 +1,48 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F + +try: + from apex.normalization import FusedLayerNorm as _FusedLayerNorm + + has_fused_layernorm = True + + class FusedLayerNorm(_FusedLayerNorm): + @torch.jit.unused + def forward(self, x): + if not x.is_cuda: + return super().forward(x) + else: + with torch.cuda.device(x.device): + return super().forward(x) + +except ImportError: + has_fused_layernorm = False + + +def LayerNorm(normalized_shape, eps=1e-5, elementwise_affine=True, export=False): + if torch.jit.is_scripting() or torch.jit.is_tracing(): + export = True + if not export and torch.cuda.is_available() and has_fused_layernorm: + return FusedLayerNorm(normalized_shape, eps, elementwise_affine) + return torch.nn.LayerNorm(normalized_shape, eps, elementwise_affine) + + +class Fp32LayerNorm(nn.LayerNorm): + def __init__(self, *args, **kwargs): + super().__init__(*args, **kwargs) + + def forward(self, input): + output = F.layer_norm( + input.float(), + self.normalized_shape, + self.weight.float() if self.weight is not None else None, + self.bias.float() if self.bias is not None else None, + self.eps, + ) + return output.type_as(input) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/learned_positional_embedding.py b/PyTorch/NLP/new-Transformer/fairseq/modules/learned_positional_embedding.py new file mode 100644 index 00000000..378d0f70 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/learned_positional_embedding.py @@ -0,0 +1,61 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Dict, Optional + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from torch import Tensor + + +class LearnedPositionalEmbedding(nn.Embedding): + """ + This module learns positional embeddings up to a fixed maximum size. + Padding ids are ignored by either offsetting based on padding_idx + or by setting padding_idx to None and ensuring that the appropriate + position ids are passed to the forward function. + """ + + def __init__(self, num_embeddings: int, embedding_dim: int, padding_idx: int): + super().__init__(num_embeddings, embedding_dim, padding_idx) + self.onnx_trace = False + if self.padding_idx is not None: + self.max_positions = self.num_embeddings - self.padding_idx - 1 + else: + self.max_positions = self.num_embeddings + + def forward( + self, + input: Tensor, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + positions: Optional[Tensor] = None, + ): + """Input is expected to be of size [bsz x seqlen].""" + assert (positions is None) or ( + self.padding_idx is None + ), "If positions is pre-computed then padding_idx should not be set." + + if positions is None: + if incremental_state is not None: + # positions is the same for every token when decoding a single step + # Without the int() cast, it doesn't work in some cases when exporting to ONNX + positions = torch.zeros( + (1, 1), device=input.device, dtype=input.dtype + ).fill_(int(self.padding_idx + input.size(1))) + else: + positions = utils.make_positions( + input, self.padding_idx, onnx_trace=self.onnx_trace + ) + return F.embedding( + positions, + self.weight, + self.padding_idx, + self.max_norm, + self.norm_type, + self.scale_grad_by_freq, + self.sparse, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/__init__.py new file mode 100644 index 00000000..3b2a99c1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/__init__.py @@ -0,0 +1,6 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .lightconv_layer import LightconvLayer # noqa diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/cuda_function_gen.py b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/cuda_function_gen.py new file mode 100644 index 00000000..a25433dd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/cuda_function_gen.py @@ -0,0 +1,289 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +def gen_forward(): + + kernels = [3, 5, 7, 15, 31, 63, 127, 255] + seqs = [32 * x for x in [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]] + + head = """ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include "lightconv_cuda.cuh" + +std::vector lightconv_cuda_forward(at::Tensor input, at::Tensor filters, int padding_l) { + + at::DeviceGuard g(input.device()); + const auto minibatch = input.size(0); + const auto numFeatures = input.size(1); + const auto sequenceLength = input.size(2); + + const auto numHeads = filters.size(0); + const auto filterSize = filters.size(1); + + const auto numFiltersInBlock = numFeatures / numHeads; + + const dim3 blocks(minibatch, numFeatures); + + auto output = at::zeros_like(input); + auto stream = at::cuda::getCurrentCUDAStream(); +""" + + sequence_if = """ + if (sequenceLength <= {seq}) {{ + switch(filterSize) {{ +""" + + case_k = """ + case {k}: +""" + + main_block = """ + if (padding_l == {pad}) {{ + AT_DISPATCH_FLOATING_TYPES_AND_HALF(input.scalar_type(), "lightconv_forward", ([&] {{ + lightconv_forward_kernel<{k}, {b_size}, {pad}, scalar_t> + <<>>( + input.data(), + filters.data(), + minibatch, + sequenceLength, + numFeatures, + numFiltersInBlock, + output.data()); + }})); + }} else +""" + + bad_padding = """ + { + std::cout << "WARNING: Unsupported padding size - skipping forward pass" << std::endl; + } + break; +""" + + bad_filter = """ + default: + std::cout << "WARNING: Unsupported filter length passed - skipping forward pass" << std::endl; + } +""" + + con_else = """ + } else +""" + + final_else = """ + { + switch(filterSize) { +""" + + final_return = """ + } + + return {output}; +} +""" + + with open("lightconv_cuda_forward.cu", "w") as forward: + forward.write(head) + for seq in seqs: + forward.write(sequence_if.format(seq=seq)) + for k in kernels: + forward.write(case_k.format(k=k)) + for pad in [k // 2, k - 1]: + forward.write(main_block.format(k=k, b_size=seq, pad=pad)) + forward.write(bad_padding) + forward.write(bad_filter) + forward.write(con_else) + + forward.write(final_else) + for k in kernels: + forward.write(case_k.format(k=k)) + for pad in [k // 2, k - 1]: + forward.write(main_block.format(k=k, b_size=seq, pad=pad)) + forward.write(bad_padding) + forward.write(bad_filter) + forward.write(final_return) + + +def gen_backward(): + + head = """ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include "lightconv_cuda.cuh" + +std::vector lightconv_cuda_backward( + at::Tensor gradOutput, + int padding_l, + at::Tensor input, + at::Tensor filters) { + + // gradWrtInput + const int minibatch = input.size(0); + const int numFeatures = input.size(1); + const int sequenceLength = input.size(2); + + const int numHeads = filters.size(0); + const int filterSize = filters.size(1); + + const dim3 gradBlocks(minibatch, numFeatures); + const dim3 weightGradFirstpassShortBlocks(minibatch, numHeads); + const dim3 weightGradSecondpassBlocks(numHeads, filterSize); + + const int numFiltersInBlock = numFeatures / numHeads; + + auto gradInput = at::zeros_like(input); + auto gradFilters = at::zeros_like(filters); + + at::DeviceGuard g(input.device()); + auto stream = at::cuda::getCurrentCUDAStream(); + + switch(filterSize) { +""" + + sequence_if = """ + if (sequenceLength <= {seq}) {{ +""" + + case_k = """ + case {k}: +""" + + main_block = """ + if (padding_l == {p}) {{ + AT_DISPATCH_FLOATING_TYPES_AND_HALF(input.scalar_type(), "lightconv_backward", ([&] {{ + lightconv_grad_wrt_input_kernel<{k}, {b_size}, {p}, scalar_t> + <<>>( + gradOutput.data(), + filters.data(), + minibatch, + sequenceLength, + numFeatures, + numFiltersInBlock, + gradInput.data()); + +""" + + weight_grad_short = """ + at::Tensor tempSumGradFilters = at::zeros({{minibatch, numHeads, filterSize}}, input.options().dtype(at::kFloat)); + lightconv_grad_wrt_weights_firstpass_short_kernel<{k}, {b_size}, {p}, scalar_t> + <<>>( + input.data(), + gradOutput.data(), + minibatch, + sequenceLength, + numFeatures, + numFiltersInBlock, + numHeads, + tempSumGradFilters.data() + ); + + lightconv_grad_wrt_weights_secondpass_short_kernel<{k}, {b_size}, scalar_t> + <<>>( + tempSumGradFilters.data(), + minibatch, + numFiltersInBlock, + gradFilters.data() + ); + }})); + }} else +""" + + weight_grad = """ + at::Tensor tempSumGradFilters = at::zeros({{minibatch, numFeatures, filterSize}}, input.options().dtype(at::kFloat)); + lightconv_grad_wrt_weights_firstpass_kernel<{k}, {b_size}, {p}, scalar_t> + <<>>( + input.data(), + gradOutput.data(), + minibatch, + sequenceLength, + numFeatures, + numFiltersInBlock, + tempSumGradFilters.data() + ); + + lightconv_grad_wrt_weights_secondpass_kernel<{k}, {b_size}, scalar_t> + <<>>( + tempSumGradFilters.data(), + minibatch, + numFiltersInBlock, + gradFilters.data() + ); + }})); + }} else +""" + + bad_padding = """ + { + std::cout << "WARNING: Unsupported padding size - skipping backward pass" << std::endl; + } +""" + + breakout = """ + break; +""" + + bad_filter = """ + default: + std::cout << "WARNING: Unsupported filter length passed - skipping backward pass" << std::endl; +""" + + con_else = """ + } else +""" + + final_else = """ + { + switch(filterSize) { +""" + + last_return = """ + } + return {gradInput, gradFilters}; +} +""" + + kernels = [3, 5, 7, 15, 31, 63, 127, 255] + seqs = [32 * x for x in [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16]] + thresh = [32, 32, 64, 128, 256, -1, -1, -1] + max_mem = [-1, -1, -1, -1, -1, 192, 96, 64] + + with open("lightconv_cuda_backward.cu", "w") as backward: + backward.write(head) + for (k, t, mem) in zip(kernels, thresh, max_mem): + backward.write(case_k.format(k=k)) + for seq in seqs: + if (t == -1 or seq <= t) and (mem == -1 or seq < mem): + backward.write(sequence_if.format(seq=seq)) + for p in [k // 2, k - 1]: + backward.write(main_block.format(k=k, b_size=seq, p=p)) + backward.write(weight_grad_short.format(k=k, b_size=seq, p=p)) + backward.write(bad_padding) + else: + for p in [k // 2, k - 1]: + backward.write(main_block.format(k=k, b_size=32, p=p)) + backward.write(weight_grad.format(k=k, b_size=32, p=p)) + backward.write(bad_padding) + backward.write(breakout) + break + backward.write(con_else) + backward.write(bad_filter) + backward.write(last_return) + + +if __name__ == "__main__": + gen_forward() + gen_backward() diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda.cpp b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda.cpp new file mode 100644 index 00000000..ece47a8d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda.cpp @@ -0,0 +1,51 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include +#include + +std::vector +lightconv_cuda_forward(at::Tensor input, at::Tensor filters, int padding_l); + +std::vector lightconv_cuda_backward( + at::Tensor gradOutput, + int padding_l, + at::Tensor input, + at::Tensor filters); + +#define CHECK_CUDA(x) \ + AT_ASSERTM(x.type().is_cuda(), #x " must be a CUDA tensor") +#define CHECK_CONTIGUOUS(x) \ + AT_ASSERTM(x.is_contiguous(), #x " must be contiguous") +#define CHECK_INPUT(x) \ + CHECK_CUDA(x); \ + CHECK_CONTIGUOUS(x) + +std::vector +lightconv_forward(at::Tensor input, at::Tensor filters, int padding_l) { + CHECK_INPUT(input); + CHECK_INPUT(filters); + + return lightconv_cuda_forward(input, filters, padding_l); +} + +std::vector lightconv_backward( + at::Tensor gradOutput, + int padding_l, + at::Tensor input, + at::Tensor filters) { + CHECK_INPUT(gradOutput); + CHECK_INPUT(input); + CHECK_INPUT(filters); + + return lightconv_cuda_backward(gradOutput, padding_l, input, filters); +} + +PYBIND11_MODULE(TORCH_EXTENSION_NAME, m) { + m.def("forward", &lightconv_forward, "lighconv forward (CUDA)"); + m.def("backward", &lightconv_backward, "lighconv backward (CUDA)"); +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda.cuh b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda.cuh new file mode 100644 index 00000000..610ab399 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda.cuh @@ -0,0 +1,79 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include +#include + +#include +#include + +#include +#include +#include +#include +#include +#include + +#include +#include + +#define SHFL_MASK 0xffffffff + +template +__global__ void lightconv_forward_kernel( + const scalar_t* input, + const scalar_t* filters, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + scalar_t* output); + +template +__global__ void lightconv_grad_wrt_input_kernel( + const scalar_t* input, + const scalar_t* filters, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + scalar_t* output); + +template +__global__ void lightconv_grad_wrt_weights_firstpass_short_kernel( + const scalar_t* input, + const scalar_t* gradInput, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + int numHeads, + float* output); + +template +__global__ void lightconv_grad_wrt_weights_secondpass_short_kernel( + const float* input, + const int minibatch, + const int numFiltersInBlock, + scalar_t* output); + +template +__global__ void lightconv_grad_wrt_weights_firstpass_kernel( + const scalar_t* input, + const scalar_t* gradInput, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + float* output); + +template +__global__ void lightconv_grad_wrt_weights_secondpass_kernel( + const float* input, + const int minibatch, + const int numFiltersInBlock, + scalar_t* output); diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda_kernel.cu b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda_kernel.cu new file mode 100644 index 00000000..cdf31d5d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_cuda_kernel.cu @@ -0,0 +1,400 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +#include "../cuda_utils.cu" +#include "lightconv_cuda.cuh" +#include "lightconv_cuda_backward.cu" +#include "lightconv_cuda_forward.cu" + +template +__global__ void lightconv_forward_kernel( + const scalar_t* input, + const scalar_t* filters, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + scalar_t* output) { + const int tid = threadIdx.x; + const int batchIdx = blockIdx.x; + const int featureIdx = blockIdx.y; + const int filterIdx = featureIdx / numFiltersInBlock; + + const int IOOffset = + numFeatures * sequenceLength * batchIdx + featureIdx * sequenceLength; + const scalar_t* inputFeature = &input[IOOffset]; + scalar_t* outputFeature = &output[IOOffset]; + const scalar_t* inputFilter = &filters[filterIdx * FS]; + + assert(blockDim.x == SB); + + scalar_t filter[FS]; +#pragma unroll + for (int i = 0; i < FS; ++i) { + filter[i] = inputFilter[i]; + } + + __shared__ scalar_t temp[SB + FS]; + zeroSharedMem(temp); + + const int numIterations = divUp(sequenceLength, SB); + + for (int i = 0; i < numIterations; ++i) { + // Read input into shared memory + const int inputOffset = i * SB; + + load_input_to_shared( + inputFeature, + inputOffset, + sequenceLength, + i, + numIterations, + (numIterations == 1), + temp); + + __syncthreads(); + + scalar_t out = 0; +#pragma unroll + for (int j = 0; j < FS; ++j) { + out += filter[j] * temp[tid + j]; + } + + // Write output + const int outputOffset = inputOffset; + if ((outputOffset + tid) < sequenceLength) { + outputFeature[outputOffset + tid] = out; + } + + __syncthreads(); + } +} + +template +__global__ void lightconv_grad_wrt_input_kernel( + const scalar_t* input, + const scalar_t* filters, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + scalar_t* output) { + // input grad kernel is similar to forward kernel + const int tid = threadIdx.x; + const int batchIdx = blockIdx.x; + const int featureIdx = blockIdx.y; + const int filterIdx = featureIdx / numFiltersInBlock; + + const int IOOffset = + numFeatures * sequenceLength * batchIdx + featureIdx * sequenceLength; + const scalar_t* inputFeature = &input[IOOffset]; + scalar_t* outputFeature = &output[IOOffset]; + const scalar_t* inputFilter = &filters[filterIdx * FS]; + + assert(blockDim.x == SB); + + scalar_t filter[FS]; + +// The only change is loading the filter in reverse +#pragma unroll + for (int i = 0; i < FS; ++i) { + filter[i] = inputFilter[FS - i - 1]; + } + + __shared__ scalar_t temp[SB + FS]; + const int padding = FS - padding_l - 1; + zeroSharedMem(temp); + + __syncthreads(); + + const int numIterations = divUp(sequenceLength, SB); + + for (int i = 0; i < numIterations; ++i) { + // Read input into shared memory + const int inputOffset = i * SB; + + load_input_to_shared( + inputFeature, + inputOffset, + sequenceLength, + i, + numIterations, + false, + temp); + + __syncthreads(); + + scalar_t out = 0; +#pragma unroll + for (int j = 0; j < FS; ++j) { + out += filter[j] * temp[tid + j]; + } + + // Write output + const int outputOffset = inputOffset; + if ((outputOffset + tid) < sequenceLength) { + outputFeature[outputOffset + tid] = out; + } + + __syncthreads(); + } +} + +// This is by far the most expensive kernel in terms of time taken. +// Can be 16x slower than the forward or grad_wrt_input when filter size is 31 +template +__global__ void lightconv_grad_wrt_weights_firstpass_short_kernel( + const scalar_t* input, + const scalar_t* gradInput, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + int numHeads, + float* output) { + const int tid = threadIdx.x; + const int batchIdx = blockIdx.x; + const int filterIdx = blockIdx.y; + + const int numIterations = divUp(sequenceLength, SB); + + float* tempOutputGradWeight = &output[filterIdx * FS * minibatch]; + + assert(blockDim.x == SB); + + __shared__ scalar_t tempInput[SB + FS]; + __shared__ scalar_t tempGradInput[SB + FS]; + + // local weight accumulation + float accumWeights[FS]; + + // Initialize memory + for (int i = 0; i < FS; ++i) { + accumWeights[i] = float(0.0); + } + + // loop over each sequence within filterblock + for (int idxInFilterBlock = 0; idxInFilterBlock < numFiltersInBlock; + ++idxInFilterBlock) { + const int featureOffset = batchIdx * numFeatures * sequenceLength + + (filterIdx * numFiltersInBlock + idxInFilterBlock) * sequenceLength; + const scalar_t* inputFeature = &input[featureOffset]; + const scalar_t* gradInputFeature = &gradInput[featureOffset]; + + zeroSharedMem(tempInput); + zeroSharedMem(tempGradInput); + __syncthreads(); + + for (int i = 0; i < numIterations; ++i) { + const int inputOffset = i * SB; + + load_input_to_shared( + inputFeature, + inputOffset, + sequenceLength, + i, + numIterations, + false, + tempInput); + load_input_to_shared( + gradInputFeature, + inputOffset, + sequenceLength, + i, + numIterations, + false, + tempGradInput); + + __syncthreads(); + + const int gradIndex = (FS / 2) + tid; + scalar_t tempGrad = tempGradInput[gradIndex]; + +#pragma unroll + for (int j = 0; j < FS; j++) { + const int inputIndex = tid + j; + accumWeights[j] += tempInput[inputIndex] * tempGrad; + } + + __syncthreads(); + } + } + + // Row-major sum + for (int filterWeightIdx = 0; filterWeightIdx < FS; ++filterWeightIdx) { + float temp; + if (tid < sequenceLength) { + temp = accumWeights[filterWeightIdx]; + } else { + temp = float(0.0); + } + + const int outputOffset = filterWeightIdx * minibatch + batchIdx; + + temp = blockReduce(temp); + + if (tid == 0) { + tempOutputGradWeight[outputOffset] = temp; + } + } +} + +template +__global__ void lightconv_grad_wrt_weights_secondpass_short_kernel( + const float* input, + const int minibatch, + const int numFiltersInBlock, + scalar_t* output) { + assert(blockDim.x == SB); + + const int tid = threadIdx.x; + + const int filterIdx = blockIdx.x; + const int filterWeightIdx = blockIdx.y; + + const int inputOffset = + filterIdx * FS * minibatch + filterWeightIdx * minibatch; + const float* tempInput = &input[inputOffset]; + + // read into shared memory for reduction + int readIndex = tid; + + float sum = 0.0; + while (readIndex < minibatch) { + sum += tempInput[readIndex]; + readIndex += SB; + } + + float temp = blockReduce(sum); + + if (tid == 0) { + output[blockIdx.x * FS + blockIdx.y] = temp; + } +} + +// This is by far the most expensive kernel in terms of time taken. +// Can be 16x slower than the forward or grad_wrt_input when filter size is 31 +template +__global__ void lightconv_grad_wrt_weights_firstpass_kernel( + const scalar_t* input, + const scalar_t* gradInput, + int minibatch, + int sequenceLength, + int numFeatures, + int numFiltersInBlock, + float* output) { + assert(blockDim.x == SB); + + const int tid = threadIdx.x; + const int batchIdx = blockIdx.x; + const int featureIdx = blockIdx.y; + const int filterIdx = featureIdx / numFiltersInBlock; + const int idxInFilterBlock = featureIdx % numFiltersInBlock; + + const int numIterations = divUp(sequenceLength, SB); + + float temp; + + __shared__ scalar_t tempInput[SB + FS]; + __shared__ scalar_t tempGradInput[SB + FS]; + zeroSharedMem(tempInput); + zeroSharedMem(tempGradInput); + __syncthreads(); + + float accumWeights[FS]; + + for (int i = 0; i < FS; ++i) { + accumWeights[i] = float(0.0); + } + + const int IOOffset = + batchIdx * numFeatures * sequenceLength + featureIdx * sequenceLength; + const scalar_t* inputFeature = &input[IOOffset]; + const scalar_t* gradInputFeature = &gradInput[IOOffset]; + float* tempOutputGradWeight = + &output[filterIdx * FS * minibatch * numFiltersInBlock]; + + for (int i = 0; i < numIterations; ++i) { + const int inputOffset = i * SB; + + load_input_to_shared( + inputFeature, + inputOffset, + sequenceLength, + i, + numIterations, + false, + tempInput); + load_input_to_shared( + gradInputFeature, + inputOffset, + sequenceLength, + i, + numIterations, + false, + tempGradInput); + __syncthreads(); + +#pragma unroll + for (int j = 0; j < FS; ++j) { + accumWeights[j] += tempInput[tid + j] * tempGradInput[tid + (FS / 2)]; + } + + __syncthreads(); + } + + // Row-major sum + for (int filterWeightIdx = 0; filterWeightIdx < FS; ++filterWeightIdx) { + // Write to shared memory before reduction + if (tid < sequenceLength) { + temp = accumWeights[filterWeightIdx]; + } else { + temp = float(0.0); + } + + temp = blockReduce(temp); + + const int outputOffset = filterWeightIdx * minibatch * numFiltersInBlock + + batchIdx * numFiltersInBlock + idxInFilterBlock; + + if (tid == 0) { + tempOutputGradWeight[outputOffset] = temp; + } + } +} + +template +__global__ void lightconv_grad_wrt_weights_secondpass_kernel( + const float* input, + const int minibatch, + const int numFiltersInBlock, + scalar_t* output) { + assert(blockDim.x == SB); + const int tid = threadIdx.x; + + // What is the id within a minibatch + const int filterIdx = blockIdx.x; + const int filterWeightIdx = blockIdx.y; + + const int inputOffset = filterIdx * FS * minibatch * numFiltersInBlock + + filterWeightIdx * minibatch * numFiltersInBlock; + const float* tempInput = &input[inputOffset]; + + int readIndex = tid; + + float sum = float(0.0); + while (readIndex < (minibatch * numFiltersInBlock)) { + sum += tempInput[readIndex]; + readIndex += SB; + } + + float temp = blockReduce(sum); + + if (tid == 0) { + output[blockIdx.x * FS + blockIdx.y] = temp; + } +} diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_layer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_layer.py new file mode 100644 index 00000000..e7e597f4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/lightconv_layer.py @@ -0,0 +1,137 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import lightconv_cuda +import torch +import torch.nn.functional as F +from fairseq import utils +from fairseq.incremental_decoding_utils import with_incremental_state +from fairseq.modules.fairseq_dropout import FairseqDropout +from torch import nn +from torch.autograd import Function + + +class lightconvFunction(Function): + @staticmethod + def forward(ctx, x, weights, padding_l): + ctx.padding_l = padding_l + outputs = lightconv_cuda.forward(x, weights, padding_l) + variables = [x, weights] + ctx.save_for_backward(*variables) + return outputs[0] + + @staticmethod + def backward(ctx, grad_output): + outputs = lightconv_cuda.backward( + grad_output.contiguous(), ctx.padding_l, *ctx.saved_tensors + ) + grad_input, grad_weights = outputs + return grad_input, grad_weights, None + + +@with_incremental_state +class LightconvLayer(nn.Module): + def __init__( + self, + input_size, + kernel_size=1, + padding_l=None, + weight_softmax=False, + num_heads=1, + weight_dropout=0.0, + bias=False, + ): + super(LightconvLayer, self).__init__() + self.input_size = input_size + self.kernel_size = kernel_size + self.padding_l = padding_l + self.num_heads = num_heads + self.weight_softmax = weight_softmax + self.weight_dropout_module = FairseqDropout( + weight_dropout, module_name=self.__class__.__name__ + ) + + self.weight = nn.Parameter(torch.Tensor(num_heads, kernel_size)) + if bias: + self.bias = nn.Parameter(torch.Tensor(input_size)) + else: + self.bias = None + self.reset_parameters() + + def upgrade_state_dict_named(self, state_dict, name): + prefix = name + "." if name != "" else "" + for k, v in state_dict.items(): + if k.endswith(prefix + "weight"): + if v.dim() == 3 and v.size(1) == 1: + state_dict[k] = v.squeeze(1) + + def reset_parameters(self): + nn.init.xavier_uniform_(self.weight) + if self.bias is not None: + nn.init.constant_(self.bias, 0.0) + + def forward(self, x, incremental_state=None): + + # during inference time, incremental BMM is faster + if incremental_state is not None: + T, B, C = x.size() + K, H = self.kernel_size, self.num_heads + R = C // H + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is None: + input_buffer = x.new() + x_unfold = torch.cat([input_buffer, x.unsqueeze(3)], dim=3) + if self.kernel_size > 1: + self._set_input_buffer( + incremental_state, x_unfold[:, :, :, -self.kernel_size + 1 :] + ) + x_unfold = x_unfold.view(T * B * H, R, -1) + + weight = self.weight + if self.weight_softmax: + weight = F.softmax(weight.float(), dim=1).type_as(weight) + + weight = weight[:, -x_unfold.size(2) :] + + K = weight.size(1) + + weight = ( + weight.view(1, H, K) + .expand(T * B, H, K) + .contiguous() + .view(T * B * H, K, 1) + ) + + weight = self.weight_dropout_module(weight) + output = torch.bmm(x_unfold, weight) # T*B*H x R x 1 + output = output.view(T, B, C) + return output + + # during training time, use CUDA kernel + else: + x = x.permute(1, 2, 0).contiguous() + weight = self.weight + if self.weight_softmax: + weight = F.softmax(self.weight, -1) + if self.weight_dropout_module.p: + weight = self.weight_dropout_module(weight) + return lightconvFunction.apply(x, weight, self.padding_l).permute(2, 0, 1) + + def reorder_incremental_state(self, incremental_state, new_order): + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is not None: + input_buffer = input_buffer.index_select(1, new_order) + self._set_input_buffer(incremental_state, input_buffer) + + def _get_input_buffer(self, incremental_state): + return utils.get_incremental_state(self, incremental_state, "input_buffer") + + def _set_input_buffer(self, incremental_state, new_buffer): + return utils.set_incremental_state( + self, incremental_state, "input_buffer", new_buffer + ) + + def half(self): + return self._apply(lambda t: t.half() if t.is_floating_point() else t) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/setup.py b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/setup.py new file mode 100644 index 00000000..052635be --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lightconv_layer/setup.py @@ -0,0 +1,23 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from setuptools import setup +from torch.utils.cpp_extension import BuildExtension, CUDAExtension + + +setup( + name="lightconv_layer", + ext_modules=[ + CUDAExtension( + "lightconv_cuda", + [ + "lightconv_cuda.cpp", + "lightconv_cuda_kernel.cu", + ], + ), + ], + cmdclass={"build_ext": BuildExtension}, +) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lightweight_convolution.py b/PyTorch/NLP/new-Transformer/fairseq/modules/lightweight_convolution.py new file mode 100644 index 00000000..ec11a950 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lightweight_convolution.py @@ -0,0 +1,310 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F +from fairseq import utils +from fairseq.incremental_decoding_utils import with_incremental_state +from fairseq.modules.fairseq_dropout import FairseqDropout +from fairseq.modules.unfold import unfold1d + + +def LightweightConv( + input_size, + kernel_size=1, + padding_l=None, + num_heads=1, + weight_dropout=0.0, + weight_softmax=False, + bias=False, +): + if torch.cuda.is_available(): + try: + from fairseq.modules.lightconv_layer import LightconvLayer + + return LightconvLayer( + input_size, + kernel_size=kernel_size, + padding_l=padding_l, + num_heads=num_heads, + weight_dropout=weight_dropout, + weight_softmax=weight_softmax, + bias=bias, + ) + except ImportError as e: + print(e) + return LightweightConv1dTBC( + input_size, + kernel_size=kernel_size, + padding_l=padding_l, + num_heads=num_heads, + weight_dropout=weight_dropout, + weight_softmax=weight_softmax, + bias=bias, + ) + + +class LightweightConv1d(nn.Module): + """Lightweight Convolution assuming the input is BxCxT + This is just an example that explains LightConv clearer than the TBC version. + We don't use this module in the model. + + Args: + input_size: # of channels of the input and output + kernel_size: convolution channels + padding: padding + num_heads: number of heads used. The weight is of shape + `(num_heads, 1, kernel_size)` + weight_softmax: normalize the weight with softmax before the convolution + + Shape: + Input: BxCxT, i.e. (batch_size, input_size, timesteps) + Output: BxCxT, i.e. (batch_size, input_size, timesteps) + + Attributes: + weight: the learnable weights of the module of shape + `(num_heads, 1, kernel_size)` + bias: the learnable bias of the module of shape `(input_size)` + """ + + def __init__( + self, + input_size, + kernel_size=1, + padding=0, + num_heads=1, + weight_softmax=False, + bias=False, + weight_dropout=0.0, + ): + super().__init__() + self.input_size = input_size + self.kernel_size = kernel_size + self.num_heads = num_heads + self.padding = padding + self.weight_softmax = weight_softmax + self.weight = nn.Parameter(torch.Tensor(num_heads, 1, kernel_size)) + + if bias: + self.bias = nn.Parameter(torch.Tensor(input_size)) + else: + self.bias = None + self.weight_dropout_module = FairseqDropout( + weight_dropout, module_name=self.__class__.__name__ + ) + self.reset_parameters() + + def reset_parameters(self): + nn.init.xavier_uniform_(self.weight) + if self.bias is not None: + nn.init.constant_(self.bias, 0.0) + + def forward(self, input): + """ + input size: B x C x T + output size: B x C x T + """ + B, C, T = input.size() + H = self.num_heads + + weight = self.weight + if self.weight_softmax: + weight = F.softmax(weight, dim=-1) + + weight = self.weight_dropout_module(weight) + # Merge every C/H entries into the batch dimension (C = self.input_size) + # B x C x T -> (B * C/H) x H x T + # One can also expand the weight to C x 1 x K by a factor of C/H + # and do not reshape the input instead, which is slow though + input = input.view(-1, H, T) + output = F.conv1d(input, weight, padding=self.padding, groups=self.num_heads) + output = output.view(B, C, T) + if self.bias is not None: + output = output + self.bias.view(1, -1, 1) + + return output + + +@with_incremental_state +class LightweightConv1dTBC(nn.Module): + """Lightweight Convolution assuming the input is TxBxC + Args: + input_size: # of channels of the input + kernel_size: convolution channels + padding_l: padding to the left when using "same" padding + num_heads: number of heads used. The weight is of shape (num_heads, 1, kernel_size) + weight_dropout: the drop rate of the DropConnect to drop the weight + weight_softmax: normalize the weight with softmax before the convolution + bias: use bias + + Shape: + Input: TxBxC, i.e. (timesteps, batch_size, input_size) + Output: TxBxC, i.e. (timesteps, batch_size, input_size) + + Attributes: + weight: the learnable weights of the module of shape + `(num_heads, 1, kernel_size)` + bias: the learnable bias of the module of shape `(input_size)` + """ + + def __init__( + self, + input_size, + kernel_size=1, + padding_l=None, + num_heads=1, + weight_dropout=0.0, + weight_softmax=False, + bias=False, + ): + super().__init__() + self.input_size = input_size + self.kernel_size = kernel_size + self.padding_l = padding_l + self.num_heads = num_heads + self.weight_dropout_module = FairseqDropout( + weight_dropout, module_name=self.__class__.__name__ + ) + self.weight_softmax = weight_softmax + + self.weight = nn.Parameter(torch.Tensor(num_heads, 1, kernel_size)) + if bias: + self.bias = nn.Parameter(torch.Tensor(input_size)) + else: + self.bias = None + + self.reset_parameters() + self.onnx_trace = False + + def reset_parameters(self): + nn.init.xavier_uniform_(self.weight) + if self.bias is not None: + nn.init.constant_(self.bias, 0.0) + + def forward(self, x, incremental_state=None, unfold=False): + """Assuming the input, x, of the shape T x B x C and producing an output in the shape T x B x C + args: + x: Input of shape T x B x C, i.e. (timesteps, batch_size, input_size) + incremental_state: A dict to keep the state + unfold: unfold the input or not. If not, we use the matrix trick instead + """ + unfold = unfold or (incremental_state is not None) + + if unfold: + output = self._forward_unfolded(x, incremental_state) + else: + output = self._forward_expanded(x, incremental_state) + + if self.bias is not None: + output = output + self.bias.view(1, 1, -1) + return output + + def prepare_for_onnx_export_(self): + self.onnx_trace = True + + def _forward_unfolded(self, x, incremental_state): + """The conventional implementation of convolutions. + Unfolding the input by having a window shifting to the right.""" + T, B, C = x.size() + K, H = self.kernel_size, self.num_heads + R = C // H + assert R * H == C == self.input_size + + weight = self.weight.view(H, K) + if incremental_state is not None: + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is None: + input_buffer = x.new() + x_unfold = torch.cat([input_buffer, x.unsqueeze(3)], dim=3) + if self.kernel_size > 1: + self._set_input_buffer( + incremental_state, x_unfold[:, :, :, -self.kernel_size + 1 :] + ) + x_unfold = x_unfold.view(T * B * H, R, -1) + else: + # unfold the input: T x B x C --> T' x B x C x K + x_unfold = unfold1d(x, self.kernel_size, self.padding_l, 0) + x_unfold = x_unfold.view(T * B * H, R, K) + + if self.weight_softmax: + weight = utils.softmax(weight, dim=1, onnx_trace=self.onnx_trace).type_as( + weight + ) + + if incremental_state is not None: + weight = weight[:, -x_unfold.size(2) :] + K = weight.size(1) + + weight = ( + weight.view(1, H, K).expand(T * B, H, K).contiguous().view(T * B * H, K, 1) + ) + + weight = self.weight_dropout_module(weight) + output = torch.bmm(x_unfold, weight) # T*B*H x R x 1 + output = output.view(T, B, C) + return output + + def _forward_expanded(self, x, incremental_state): + """Turn the convolution filters into band matrices and do matrix multiplication. + This is faster when the sequence is short, but less memory efficient. + This is not used in the decoder during inference. + """ + T, B, C = x.size() + K, H = self.kernel_size, self.num_heads + R = C // H + assert R * H == C == self.input_size + + weight = self.weight.view(H, K) + if self.weight_softmax: + weight = utils.softmax(weight, dim=1, onnx_trace=self.onnx_trace).type_as( + weight + ) + weight = weight.view(1, H, K).expand(T * B, H, K).contiguous() + weight = weight.view(T, B * H, K).transpose(0, 1) + + x = x.view(T, B * H, R).transpose(0, 1) + P = self.padding_l + if K > T and P == K - 1: + weight = weight.narrow(2, K - T, T) + K, P = T, T - 1 + # turn the convolution filters into band matrices + weight_expanded = weight.new_zeros(B * H, T, T + K - 1, requires_grad=False) + weight_expanded.as_strided((B * H, T, K), (T * (T + K - 1), T + K, 1)).copy_( + weight + ) + weight_expanded = weight_expanded.narrow(2, P, T) + weight_expanded = self.weight_dropout_module(weight_expanded) + + output = torch.bmm(weight_expanded, x) + output = output.transpose(0, 1).contiguous().view(T, B, C) + return output + + def reorder_incremental_state(self, incremental_state, new_order): + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is not None: + input_buffer = input_buffer.index_select(1, new_order) + self._set_input_buffer(incremental_state, input_buffer) + + def _get_input_buffer(self, incremental_state): + return utils.get_incremental_state(self, incremental_state, "input_buffer") + + def _set_input_buffer(self, incremental_state, new_buffer): + return utils.set_incremental_state( + self, incremental_state, "input_buffer", new_buffer + ) + + def extra_repr(self): + s = "{}, kernel_size={}, padding_l={}, num_heads={}, weight_softmax={}, bias={}".format( + self.input_size, + self.kernel_size, + self.padding_l, + self.num_heads, + self.weight_softmax, + self.bias is not None, + ) + if self.weight_dropout_module.p > 0.0: + s += ", weight_dropout={}".format(self.weight_dropout_module.p) + return s diff --git a/PyTorch/NLP/Transformer/fairseq/modules/linearized_convolution.py b/PyTorch/NLP/new-Transformer/fairseq/modules/linearized_convolution.py similarity index 60% rename from PyTorch/NLP/Transformer/fairseq/modules/linearized_convolution.py rename to PyTorch/NLP/new-Transformer/fairseq/modules/linearized_convolution.py index 63a048b8..1c7a9f09 100644 --- a/PyTorch/NLP/Transformer/fairseq/modules/linearized_convolution.py +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/linearized_convolution.py @@ -1,18 +1,20 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. +# Copyright (c) Facebook, Inc. and its affiliates. # -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. import torch import torch.nn.functional as F - from fairseq import utils +from fairseq.incremental_decoding_utils import with_incremental_state from .conv_tbc import ConvTBC +from typing import Dict, Optional +from torch import Tensor + +@with_incremental_state class LinearizedConvolution(ConvTBC): """An optimized version of nn.Conv1d. @@ -27,21 +29,38 @@ class LinearizedConvolution(ConvTBC): self._linearized_weight = None self.register_backward_hook(self._clear_linearized_weight) - def forward(self, input, incremental_state=None): + def state_dict(self, destination=None, prefix="", keep_vars=False): + state = ConvTBC.state_dict(self, destination, prefix, keep_vars=keep_vars) + # don't store redundant _linearized_weight in checkpoints + if prefix + "_linearized_weight" in state: + del state[prefix + "_linearized_weight"] + return state + + def upgrade_state_dict_named(self, state_dict, name): + prefix = name + "." if name != "" else "" + if prefix + "_linearized_weight" in state_dict: + del state_dict[prefix + "_linearized_weight"] + + @torch.jit.export + def forward( + self, + input, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + ): """ - Input: - Time x Batch x Channel during training - Batch x Time x Channel during inference Args: incremental_state: Used to buffer signal; if not None, then input is expected to contain a single frame. If the input order changes between time steps, call reorder_incremental_state. + Input: + Time x Batch x Channel during training + Batch x Time x Channel during inference """ if incremental_state is None: - output = super().forward(input) + output = self.conv_tbc(input) if self.kernel_size[0] > 1 and self.padding[0] > 0: # remove future timesteps added by padding - output = output[:-self.padding[0], :, :] + output = output[: -self.padding[0], :, :] return output # reshape weight @@ -65,25 +84,42 @@ class LinearizedConvolution(ConvTBC): output = F.linear(input.view(bsz, -1), weight, self.bias) return output.view(bsz, 1, -1) - def reorder_incremental_state(self, incremental_state, new_order): + @torch.jit.unused + def reorder_incremental_state( + self, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]], + new_order, + ): input_buffer = self._get_input_buffer(incremental_state) if input_buffer is not None: input_buffer = input_buffer.index_select(0, new_order) self._set_input_buffer(incremental_state, input_buffer) - def _get_input_buffer(self, incremental_state): - return utils.get_incremental_state(self, incremental_state, 'input_buffer') + @torch.jit.unused + def _get_input_buffer( + self, incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] + ): + return utils.get_incremental_state(self, incremental_state, "input_buffer") - def _set_input_buffer(self, incremental_state, new_buffer): - return utils.set_incremental_state(self, incremental_state, 'input_buffer', new_buffer) + @torch.jit.unused + def _set_input_buffer( + self, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]], + new_buffer, + ): + return utils.set_incremental_state( + self, incremental_state, "input_buffer", new_buffer + ) + @torch.jit.unused def _get_linearized_weight(self): if self._linearized_weight is None: kw = self.kernel_size[0] weight = self.weight.transpose(2, 1).transpose(1, 0).contiguous() assert weight.size() == (self.out_channels, kw, self.in_channels) - self._linearized_weight = weight.view(self.out_channels, -1) + return weight.view(self.out_channels, -1) return self._linearized_weight + @torch.jit.unused def _clear_linearized_weight(self, *args): self._linearized_weight = None diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/location_attention.py b/PyTorch/NLP/new-Transformer/fairseq/modules/location_attention.py new file mode 100644 index 00000000..dbbbfb9f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/location_attention.py @@ -0,0 +1,83 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn as nn +import torch +import torch.nn.functional as F + + +class LocationAttention(nn.Module): + """ + Attention-Based Models for Speech Recognition + https://arxiv.org/pdf/1506.07503.pdf + + :param int encoder_dim: # projection-units of encoder + :param int decoder_dim: # units of decoder + :param int attn_dim: attention dimension + :param int conv_dim: # channels of attention convolution + :param int conv_kernel_size: filter size of attention convolution + """ + + def __init__( + self, + attn_dim, + encoder_dim, + decoder_dim, + attn_state_kernel_size, + conv_dim, + conv_kernel_size, + scaling=2.0, + ): + super(LocationAttention, self).__init__() + self.attn_dim = attn_dim + self.decoder_dim = decoder_dim + self.scaling = scaling + self.proj_enc = nn.Linear(encoder_dim, attn_dim) + self.proj_dec = nn.Linear(decoder_dim, attn_dim, bias=False) + self.proj_attn = nn.Linear(conv_dim, attn_dim, bias=False) + self.conv = nn.Conv1d( + attn_state_kernel_size, + conv_dim, + 2 * conv_kernel_size + 1, + padding=conv_kernel_size, + bias=False, + ) + self.proj_out = nn.Sequential(nn.Tanh(), nn.Linear(attn_dim, 1)) + + self.proj_enc_out = None # cache + + def clear_cache(self): + self.proj_enc_out = None + + def forward(self, encoder_out, encoder_padding_mask, decoder_h, attn_state): + """ + :param torch.Tensor encoder_out: padded encoder hidden state B x T x D + :param torch.Tensor encoder_padding_mask: encoder padding mask + :param torch.Tensor decoder_h: decoder hidden state B x D + :param torch.Tensor attn_prev: previous attention weight B x K x T + :return: attention weighted encoder state (B, D) + :rtype: torch.Tensor + :return: previous attention weights (B x T) + :rtype: torch.Tensor + """ + bsz, seq_len, _ = encoder_out.size() + if self.proj_enc_out is None: + self.proj_enc_out = self.proj_enc(encoder_out) + + # B x K x T -> B x C x T + attn = self.conv(attn_state) + # B x C x T -> B x T x C -> B x T x D + attn = self.proj_attn(attn.transpose(1, 2)) + + if decoder_h is None: + decoder_h = encoder_out.new_zeros(bsz, self.decoder_dim) + dec_h = self.proj_dec(decoder_h).view(bsz, 1, self.attn_dim) + + out = self.proj_out(attn + self.proj_enc_out + dec_h).squeeze(2) + out.masked_fill_(encoder_padding_mask, -float("inf")) + + w = F.softmax(self.scaling * out, dim=1) + c = torch.sum(encoder_out * w.view(bsz, seq_len, 1), dim=1) + return c, w diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/lstm_cell_with_zoneout.py b/PyTorch/NLP/new-Transformer/fairseq/modules/lstm_cell_with_zoneout.py new file mode 100644 index 00000000..27330895 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/lstm_cell_with_zoneout.py @@ -0,0 +1,37 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn as nn + + +class LSTMCellWithZoneOut(nn.Module): + """ + Zoneout: Regularizing RNNs by Randomly Preserving Hidden Activations + https://arxiv.org/abs/1606.01305 + """ + + def __init__( + self, prob: float, input_size: int, hidden_size: int, bias: bool = True + ): + super(LSTMCellWithZoneOut, self).__init__() + self.lstm_cell = nn.LSTMCell(input_size, hidden_size, bias=bias) + self.prob = prob + if prob > 1.0 or prob < 0.0: + raise ValueError( + "zoneout probability must be in the range from " "0.0 to 1.0." + ) + + def zoneout(self, h, next_h, prob): + if isinstance(h, tuple): + return tuple([self.zoneout(h[i], next_h[i], prob) for i in range(len(h))]) + + if self.training: + mask = h.new_zeros(*h.size()).bernoulli_(prob) + return mask * h + (1 - mask) * next_h + + return prob * h + (1 - prob) * next_h + + def forward(self, x, h): + return self.zoneout(h, self.lstm_cell(x, h), self.prob) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/multihead_attention.py b/PyTorch/NLP/new-Transformer/fairseq/modules/multihead_attention.py new file mode 100644 index 00000000..43148060 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/multihead_attention.py @@ -0,0 +1,908 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from typing import Dict, List, Optional, Tuple + +import torch +import torch.nn.functional as F +from torch import Tensor, nn +from torch.nn import Parameter + +try: + from xformers.components.attention import build_attention + from xformers.components.attention.utils import maybe_merge_masks + + _xformers_available = True +except ImportError: + _xformers_available = False + +from fairseq import utils +from fairseq.incremental_decoding_utils import with_incremental_state +from fairseq.modules.fairseq_dropout import FairseqDropout +from fairseq.modules.quant_noise import quant_noise + + +# TODO: move this into xformers? +# TODO: uint8 input type should just output a bool +def _mask_for_xformers(mask: Tensor, to_dtype: Optional[torch.dtype] = None): + """ + call to pytorch multihead accepts three mask types: + - ByteTensor where non-zero means to mask + - FloatTensor which is an additive mask + - BoolTensor where True means to mask + xFormers currently accepts boolean and additive maks. For boolean masks + the values have opposite meaning. For a BoolTensor True mean to keep the value. + """ + float_types = [torch.float, torch.float16] + # If an input mask is a float it is an additive mask. Otherwise it is either uint8 or bool. + additive = mask.dtype in float_types + # If to_dype is not specified, keep same dtype as mask. + to_dtype = mask.dtype if to_dtype is None else to_dtype + to_additive = to_dtype in float_types + + if additive: + if to_additive: + return mask.to(to_dtype) + mask = mask < 0 + + if to_additive: + # return additive mask + new_mask = torch.zeros_like(mask, dtype=to_dtype) + new_mask = new_mask.masked_fill_(mask, -float("inf")) + return new_mask + + # In xFormers True is value to keep rather than value to mask + mask = ~mask.to(torch.bool) + mask = mask.to(to_dtype) + return mask + + +@with_incremental_state +class MultiheadAttention(nn.Module): + """Multi-headed attention. + + See "Attention Is All You Need" for more details. + """ + + def __init__( + self, + embed_dim, + num_heads, + kdim=None, + vdim=None, + dropout=0.0, + bias=True, + add_bias_kv=False, + add_zero_attn=False, + self_attention=False, + encoder_decoder_attention=False, + q_noise=0.0, + qn_block_size=8, + # TODO: pass in config rather than string. + # config defined in xformers.components.attention.AttentionConfig + xformers_att_config: Optional[str] = None, + xformers_blocksparse_layout: Optional[ + torch.Tensor + ] = None, # This should be part of the config + xformers_blocksparse_blocksize: Optional[ + int + ] = 16, # This should be part of the config + ): + super().__init__() + + xformers_att_config = utils.eval_str_dict(xformers_att_config) + self.use_xformers = xformers_att_config is not None + if self.use_xformers and not _xformers_available: + raise ImportError("\n\n Please install xFormers.") + self.embed_dim = embed_dim + self.kdim = kdim if kdim is not None else embed_dim + self.vdim = vdim if vdim is not None else embed_dim + self.qkv_same_dim = self.kdim == embed_dim and self.vdim == embed_dim + + self.num_heads = num_heads + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + + self.head_dim = embed_dim // num_heads + assert ( + self.head_dim * num_heads == self.embed_dim + ), "embed_dim must be divisible by num_heads" + self.scaling = self.head_dim**-0.5 + + self.self_attention = self_attention + self.encoder_decoder_attention = encoder_decoder_attention + + assert not self.self_attention or self.qkv_same_dim, ( + "Self-attention requires query, key and " "value to be of the same size" + ) + + self.k_proj = quant_noise( + nn.Linear(self.kdim, embed_dim, bias=bias), q_noise, qn_block_size + ) + self.v_proj = quant_noise( + nn.Linear(self.vdim, embed_dim, bias=bias), q_noise, qn_block_size + ) + self.q_proj = quant_noise( + nn.Linear(embed_dim, embed_dim, bias=bias), q_noise, qn_block_size + ) + + self.out_proj = quant_noise( + nn.Linear(embed_dim, embed_dim, bias=bias), q_noise, qn_block_size + ) + + if add_bias_kv: + self.bias_k = Parameter(torch.Tensor(1, 1, embed_dim)) + self.bias_v = Parameter(torch.Tensor(1, 1, embed_dim)) + else: + self.bias_k = self.bias_v = None + + self.add_zero_attn = add_zero_attn + self.beam_size = 1 + self.reset_parameters() + + if self.use_xformers: + xformers_att_config["dropout"] = xformers_att_config.get("dropout", dropout) + xformers_att_config["num_heads"] = xformers_att_config.get( + "num_heads", num_heads + ) + + if xformers_blocksparse_layout is not None: + # Could be part of a single config passed only once + xformers_att_config["block_size"] = xformers_blocksparse_blocksize + xformers_att_config["layout"] = xformers_blocksparse_layout + xformers_att_config["name"] = "blocksparse" + + self.attention = build_attention(xformers_att_config) + + self.onnx_trace = False + self.skip_embed_dim_check = False + + def prepare_for_onnx_export_(self): + self.onnx_trace = True + + def reset_parameters(self): + if self.qkv_same_dim: + # Empirically observed the convergence to be much better with + # the scaled initialization + nn.init.xavier_uniform_(self.k_proj.weight, gain=1 / math.sqrt(2)) + nn.init.xavier_uniform_(self.v_proj.weight, gain=1 / math.sqrt(2)) + nn.init.xavier_uniform_(self.q_proj.weight, gain=1 / math.sqrt(2)) + else: + nn.init.xavier_uniform_(self.k_proj.weight) + nn.init.xavier_uniform_(self.v_proj.weight) + nn.init.xavier_uniform_(self.q_proj.weight) + + nn.init.xavier_uniform_(self.out_proj.weight) + if self.out_proj.bias is not None: + nn.init.constant_(self.out_proj.bias, 0.0) + if self.bias_k is not None: + nn.init.xavier_normal_(self.bias_k) + if self.bias_v is not None: + nn.init.xavier_normal_(self.bias_v) + + def _get_reserve_head_index(self, num_heads_to_keep: int): + k_proj_heads_norm = [] + q_proj_heads_norm = [] + v_proj_heads_norm = [] + + for i in range(self.num_heads): + start_idx = i * self.head_dim + end_idx = (i + 1) * self.head_dim + k_proj_heads_norm.append( + torch.sum( + torch.abs( + self.k_proj.weight[ + start_idx:end_idx, + ] + ) + ).tolist() + + torch.sum(torch.abs(self.k_proj.bias[start_idx:end_idx])).tolist() + ) + q_proj_heads_norm.append( + torch.sum( + torch.abs( + self.q_proj.weight[ + start_idx:end_idx, + ] + ) + ).tolist() + + torch.sum(torch.abs(self.q_proj.bias[start_idx:end_idx])).tolist() + ) + v_proj_heads_norm.append( + torch.sum( + torch.abs( + self.v_proj.weight[ + start_idx:end_idx, + ] + ) + ).tolist() + + torch.sum(torch.abs(self.v_proj.bias[start_idx:end_idx])).tolist() + ) + + heads_norm = [] + for i in range(self.num_heads): + heads_norm.append( + k_proj_heads_norm[i] + q_proj_heads_norm[i] + v_proj_heads_norm[i] + ) + + sorted_head_index = sorted( + range(self.num_heads), key=lambda k: heads_norm[k], reverse=True + ) + reserve_head_index = [] + for i in range(num_heads_to_keep): + start = sorted_head_index[i] * self.head_dim + end = (sorted_head_index[i] + 1) * self.head_dim + reserve_head_index.append((start, end)) + return reserve_head_index + + def _adaptive_prune_heads(self, reserve_head_index: List[Tuple[int, int]]): + new_q_weight = [] + new_q_bias = [] + new_k_weight = [] + new_k_bias = [] + new_v_weight = [] + new_v_bias = [] + new_out_proj_weight = [] + + for ele in reserve_head_index: + start_idx, end_idx = ele + new_q_weight.append( + self.q_proj.weight[ + start_idx:end_idx, + ] + ) + new_q_bias.append(self.q_proj.bias[start_idx:end_idx]) + + new_k_weight.append( + self.k_proj.weight[ + start_idx:end_idx, + ] + ) + + new_k_bias.append(self.k_proj.bias[start_idx:end_idx]) + + new_v_weight.append( + self.v_proj.weight[ + start_idx:end_idx, + ] + ) + new_v_bias.append(self.v_proj.bias[start_idx:end_idx]) + + new_out_proj_weight.append(self.out_proj.weight[:, start_idx:end_idx]) + + new_q_weight = torch.cat(new_q_weight).detach() + new_k_weight = torch.cat(new_k_weight).detach() + new_v_weight = torch.cat(new_v_weight).detach() + new_out_proj_weight = torch.cat(new_out_proj_weight, dim=-1).detach() + new_q_weight.requires_grad = True + new_k_weight.requires_grad = True + new_v_weight.requires_grad = True + new_out_proj_weight.requires_grad = True + + new_q_bias = torch.cat(new_q_bias).detach() + new_q_bias.requires_grad = True + + new_k_bias = torch.cat(new_k_bias).detach() + new_k_bias.requires_grad = True + + new_v_bias = torch.cat(new_v_bias).detach() + new_v_bias.requires_grad = True + + self.q_proj.weight = torch.nn.Parameter(new_q_weight) + self.q_proj.bias = torch.nn.Parameter(new_q_bias) + + self.k_proj.weight = torch.nn.Parameter(new_k_weight) + self.k_proj.bias = torch.nn.Parameter(new_k_bias) + + self.v_proj.weight = torch.nn.Parameter(new_v_weight) + self.v_proj.bias = torch.nn.Parameter(new_v_bias) + + self.out_proj.weight = torch.nn.Parameter(new_out_proj_weight) + + self.num_heads = len(reserve_head_index) + self.embed_dim = self.head_dim * self.num_heads + self.q_proj.out_features = self.embed_dim + self.k_proj.out_features = self.embed_dim + self.v_proj.out_features = self.embed_dim + + def _set_skip_embed_dim_check(self): + self.skip_embed_dim_check = True + + def _pad_masks( + self, + key_padding_mask: Optional[Tensor], + attn_mask: Optional[Tensor], + ) -> Tuple[Optional[Tensor], Optional[Tensor]]: + if attn_mask is not None: + shape = attn_mask.size()[:-1] + torch.Size([1]) + attn_mask = torch.cat([attn_mask, attn_mask.new_zeros(shape)], dim=-1) + if key_padding_mask is not None: + shape = key_padding_mask.size()[:-1] + torch.Size([1]) + key_padding_mask = torch.cat( + [ + key_padding_mask, + key_padding_mask.new_zeros(shape), + ], + dim=-1, + ) + return key_padding_mask, attn_mask + + def _add_bias( + self, + k: Tensor, + v: Tensor, + key_padding_mask: Optional[Tensor], + attn_mask: Optional[Tensor], + bsz: int, + ) -> Tuple[Tensor, Tensor, Optional[Tensor], Optional[Tensor]]: + assert self.bias_k is not None + assert self.bias_v is not None + k = torch.cat([k, self.bias_k.repeat(1, bsz, 1)]) + v = torch.cat([v, self.bias_v.repeat(1, bsz, 1)]) + key_padding_mask, attn_mask = self._pad_masks( + key_padding_mask=key_padding_mask, attn_mask=attn_mask + ) + return k, v, key_padding_mask, attn_mask + + def _append_zero_attn( + self, + k: Tensor, + v: Tensor, + key_padding_mask: Optional[Tensor], + attn_mask: Optional[Tensor], + ) -> Tuple[Tensor, Tensor, Optional[Tensor], Optional[Tensor]]: + zero_attn_shape = k.size()[:-2] + torch.Size([1]) + k.size()[-1:] + k = torch.cat( + [k, torch.zeros(zero_attn_shape, dtype=k.dtype, device=k.device)], dim=-2 + ) + v = torch.cat( + [v, torch.zeros(zero_attn_shape, dtype=v.dtype, device=v.device)], dim=-2 + ) + key_padding_mask, attn_mask = self._pad_masks( + key_padding_mask=key_padding_mask, attn_mask=attn_mask + ) + return k, v, key_padding_mask, attn_mask + + def _xformers_attn_forward( + self, + query, + key: Optional[Tensor], + value: Optional[Tensor], + key_padding_mask: Optional[Tensor] = None, + need_weights: bool = True, + attn_mask: Optional[Tensor] = None, + ) -> Tuple[Tensor, Optional[Tensor]]: + + tgt_len, bsz, embed_dim = query.size() + + if key_padding_mask is not None: + assert key_padding_mask.size(0) == bsz + assert key_padding_mask.size(1) == tgt_len + + if self.self_attention: + key = query + value = query + elif self.encoder_decoder_attention: + value = key + + q = self.q_proj(query) + k = self.k_proj(key) + v = self.v_proj(value) + + if self.bias_k is not None: + assert self.bias_v is not None + k, v, attn_mask, key_padding_mask = self._add_bias( + k, v, attn_mask, key_padding_mask, bsz + ) + + def fold_heads(x): + return ( + x.contiguous() + .view(-1, bsz * self.num_heads, self.head_dim) + .transpose(0, 1) + ) + + def split_heads(x): + return ( + x.contiguous() + .view(-1, bsz, self.num_heads, self.head_dim) + .transpose(0, 1) + .transpose(1, 2) + ) + + massage = split_heads if self.attention.requires_head_dimension else fold_heads + q = massage(q) + if k is not None: + k = massage(k) + if v is not None: + v = massage(v) + + if self.add_zero_attn: + k, v, key_padding_mask, attn_mask = self._append_zero_attn( + k=k, v=v, key_padding_mask=key_padding_mask, attn_mask=attn_mask + ) + + kwargs = {} + + if attn_mask is not None and self.attention.supports_attention_mask: + attn_mask = _mask_for_xformers(attn_mask, to_dtype=q.dtype) + kwargs["att_mask"] = attn_mask + + if key_padding_mask is not None: + key_padding_mask = _mask_for_xformers(key_padding_mask, to_dtype=torch.bool) + if not self.attention.requires_separate_masks: + attn_mask = maybe_merge_masks( + attn_mask, + key_padding_mask, + batch_size=bsz, + src_len=k.size(-2), + tgt_len=q.size(-2), + num_heads=self.num_heads, + ) + key_padding_mask = None + kwargs["att_mask"] = attn_mask + if self.attention.supports_key_padding_mask: + kwargs["key_padding_mask"] = key_padding_mask + + y = self.attention(q, k, v, **kwargs) + + y = ( + y.view(bsz, self.num_heads, tgt_len, self.head_dim) + .transpose(1, 2) + .flatten(start_dim=2, end_dim=3) + .transpose(0, 1) + ) + assert list(y.size()) == [tgt_len, bsz, embed_dim] + + # Dropout not needed because already applied in attention. + # It is applied to the attention weights before matmul with v. + y = self.out_proj(y) + + # TODO: support returning attention weights if needed. + return y, None + + def forward( + self, + query, + key: Optional[Tensor], + value: Optional[Tensor], + key_padding_mask: Optional[Tensor] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + need_weights: bool = True, + static_kv: bool = False, + attn_mask: Optional[Tensor] = None, + before_softmax: bool = False, + need_head_weights: bool = False, + ) -> Tuple[Tensor, Optional[Tensor]]: + """Input shape: Time x Batch x Channel + + Args: + key_padding_mask (ByteTensor, optional): mask to exclude + keys that are pads, of shape `(batch, src_len)`, where + padding elements are indicated by 1s. + need_weights (bool, optional): return the attention weights, + averaged over heads (default: False). + attn_mask (ByteTensor, optional): typically used to + implement causal attention, where the mask prevents the + attention from looking forward in time (default: None). + before_softmax (bool, optional): return the raw attention + weights and values before the attention softmax. + need_head_weights (bool, optional): return the attention + weights for each head. Implies *need_weights*. Default: + return the average attention weights over all heads. + """ + if need_head_weights: + need_weights = True + + is_tpu = query.device.type == "xla" + + tgt_len, bsz, embed_dim = query.size() + src_len = tgt_len + if not self.skip_embed_dim_check: + assert ( + embed_dim == self.embed_dim + ), f"query dim {embed_dim} != {self.embed_dim}" + assert list(query.size()) == [tgt_len, bsz, embed_dim] + if key is not None: + src_len, key_bsz, _ = key.size() + if not torch.jit.is_scripting(): + assert value is not None + assert src_len, key_bsz == value.shape[:2] + + if ( + not self.onnx_trace + and not is_tpu # don't use PyTorch version on TPUs + and incremental_state is None + and not static_kv + # A workaround for quantization to work. Otherwise JIT compilation + # treats bias in linear module as method. + and not torch.jit.is_scripting() + # The Multihead attention implemented in pytorch forces strong dimension check + # for input embedding dimention and K,Q,V projection dimension. + # Since pruning will break the dimension check and it is not easy to modify the pytorch API, + # it is preferred to bypass the pytorch MHA when we need to skip embed_dim_check + and not self.skip_embed_dim_check + ): + assert key is not None and value is not None + + if self.use_xformers: + return self._xformers_attn_forward( + query, key, value, key_padding_mask, need_weights, attn_mask + ) + + else: + return F.multi_head_attention_forward( + query, + key, + value, + self.embed_dim, + self.num_heads, + torch.empty([0]), + torch.cat((self.q_proj.bias, self.k_proj.bias, self.v_proj.bias)), + self.bias_k, + self.bias_v, + self.add_zero_attn, + self.dropout_module.p, + self.out_proj.weight, + self.out_proj.bias, + self.training or self.dropout_module.apply_during_inference, + key_padding_mask, + need_weights, + attn_mask, + use_separate_proj_weight=True, + q_proj_weight=self.q_proj.weight, + k_proj_weight=self.k_proj.weight, + v_proj_weight=self.v_proj.weight, + ) + + if incremental_state is not None: + saved_state = self._get_input_buffer(incremental_state) + if saved_state is not None and "prev_key" in saved_state: + # previous time steps are cached - no need to recompute + # key and value if they are static + if static_kv: + assert self.encoder_decoder_attention and not self.self_attention + key = value = None + else: + saved_state = None + + if self.self_attention: + q = self.q_proj(query) + k = self.k_proj(query) + v = self.v_proj(query) + elif self.encoder_decoder_attention: + # encoder-decoder attention + q = self.q_proj(query) + if key is None: + assert value is None + k = v = None + else: + if self.beam_size > 1 and bsz == key.size(1): + # key is [T, bsz*beam_size, C], reduce to [T, bsz, C] + key = key.view(key.size(0), -1, self.beam_size, key.size(2))[ + :, :, 0, : + ] + if key_padding_mask is not None: + key_padding_mask = key_padding_mask.view( + -1, self.beam_size, key_padding_mask.size(1) + )[:, 0, :] + k = self.k_proj(key) + v = self.v_proj(key) + + else: + assert key is not None and value is not None + q = self.q_proj(query) + k = self.k_proj(key) + v = self.v_proj(value) + q *= self.scaling + + if self.bias_k is not None: + assert self.bias_v is not None + k, v, attn_mask, key_padding_mask = self._add_bias( + k, v, attn_mask, key_padding_mask, bsz + ) + + q = ( + q.contiguous() + .view(tgt_len, bsz * self.num_heads, self.head_dim) + .transpose(0, 1) + ) + kv_bsz = bsz # need default value for scripting + if k is not None: + kv_bsz = k.size(1) + k = ( + k.contiguous() + .view(-1, kv_bsz * self.num_heads, self.head_dim) + .transpose(0, 1) + ) + if v is not None: + v = ( + v.contiguous() + .view(-1, kv_bsz * self.num_heads, self.head_dim) + .transpose(0, 1) + ) + + if saved_state is not None: + # saved states are stored with shape (bsz, num_heads, seq_len, head_dim) + if "prev_key" in saved_state: + _prev_key = saved_state["prev_key"] + assert _prev_key is not None + kv_bsz = _prev_key.size(0) + prev_key = _prev_key.view(kv_bsz * self.num_heads, -1, self.head_dim) + if static_kv: + k = prev_key + else: + assert k is not None + k = torch.cat([prev_key, k], dim=1) + src_len = k.size(1) + if "prev_value" in saved_state: + _prev_value = saved_state["prev_value"] + assert _prev_value is not None + assert kv_bsz == _prev_value.size(0) + prev_value = _prev_value.view( + kv_bsz * self.num_heads, -1, self.head_dim + ) + if static_kv: + v = prev_value + else: + assert v is not None + v = torch.cat([prev_value, v], dim=1) + prev_key_padding_mask: Optional[Tensor] = None + if "prev_key_padding_mask" in saved_state: + prev_key_padding_mask = saved_state["prev_key_padding_mask"] + assert k is not None and v is not None + key_padding_mask = MultiheadAttention._append_prev_key_padding_mask( + key_padding_mask=key_padding_mask, + prev_key_padding_mask=prev_key_padding_mask, + batch_size=kv_bsz, + src_len=k.size(1), + static_kv=static_kv, + ) + + saved_state["prev_key"] = k.view(kv_bsz, self.num_heads, -1, self.head_dim) + saved_state["prev_value"] = v.view( + kv_bsz, self.num_heads, -1, self.head_dim + ) + saved_state["prev_key_padding_mask"] = key_padding_mask + # In this branch incremental_state is never None + assert incremental_state is not None + incremental_state = self._set_input_buffer(incremental_state, saved_state) + assert k is not None + assert k.size(1) == src_len + + # This is part of a workaround to get around fork/join parallelism + # not supporting Optional types. + if key_padding_mask is not None and key_padding_mask.dim() == 0: + key_padding_mask = None + + if key_padding_mask is not None: + assert key_padding_mask.size(0) == kv_bsz + assert key_padding_mask.size(1) == src_len + + if self.add_zero_attn: + assert v is not None + src_len += 1 + k, v, key_padding_mask, attn_mask = self._append_zero_attn( + k=k, v=v, key_padding_mask=key_padding_mask, attn_mask=attn_mask + ) + + if self.encoder_decoder_attention and bsz != kv_bsz: + attn_weights = torch.einsum( + "bxhtd,bhsd->bxhts", + q.view((kv_bsz, -1, self.num_heads) + q.size()[1:]), + k.view((kv_bsz, self.num_heads) + k.size()[1:]), + ) + attn_weights = attn_weights.reshape((-1,) + attn_weights.size()[-2:]) + else: + attn_weights = torch.bmm(q, k.transpose(1, 2)) + attn_weights = self.apply_sparse_mask(attn_weights, tgt_len, src_len, bsz) + + assert list(attn_weights.size()) == [bsz * self.num_heads, tgt_len, src_len] + + if attn_mask is not None: + attn_mask = attn_mask.unsqueeze(0) + if self.onnx_trace: + attn_mask = attn_mask.repeat(attn_weights.size(0), 1, 1) + attn_weights += attn_mask + + if key_padding_mask is not None: + # don't attend to padding symbols + attn_weights = attn_weights.view(bsz, self.num_heads, tgt_len, src_len) + if not is_tpu: + attn_weights = attn_weights.view( + kv_bsz, -1, self.num_heads, tgt_len, src_len + ) + attn_weights = attn_weights.masked_fill( + key_padding_mask.unsqueeze(1) + .unsqueeze(2) + .unsqueeze(3) + .to(torch.bool), + float("-inf"), + ) + else: + attn_weights = attn_weights.transpose(0, 2) + attn_weights = attn_weights.masked_fill(key_padding_mask, float("-inf")) + attn_weights = attn_weights.transpose(0, 2) + attn_weights = attn_weights.view(bsz * self.num_heads, tgt_len, src_len) + + if before_softmax: + return attn_weights, v + + attn_weights_float = utils.softmax( + attn_weights, dim=-1, onnx_trace=self.onnx_trace + ) + attn_weights = attn_weights_float.type_as(attn_weights) + attn_probs = self.dropout_module(attn_weights) + + assert v is not None + if self.encoder_decoder_attention and bsz != kv_bsz: + attn = torch.einsum( + "bxhts,bhsd->bxhtd", + attn_probs.view( + ( + kv_bsz, + -1, + self.num_heads, + ) + + attn_probs.size()[1:] + ), + v.view( + ( + kv_bsz, + self.num_heads, + ) + + v.size()[1:] + ), + ) + attn = attn.reshape((-1,) + attn.size()[-2:]) + else: + attn = torch.bmm(attn_probs, v) + assert list(attn.size()) == [bsz * self.num_heads, tgt_len, self.head_dim] + if self.onnx_trace and attn.size(1) == 1: + # when ONNX tracing a single decoder step (sequence length == 1) + # the transpose is a no-op copy before view, thus unnecessary + attn = attn.contiguous().view(tgt_len, bsz, self.embed_dim) + else: + attn = attn.transpose(0, 1).contiguous().view(tgt_len, bsz, self.embed_dim) + attn = self.out_proj(attn) + attn_weights: Optional[Tensor] = None + if need_weights: + attn_weights = attn_weights_float.view( + bsz, self.num_heads, tgt_len, src_len + ).transpose(1, 0) + if not need_head_weights: + # average attention weights over heads + attn_weights = attn_weights.mean(dim=0) + + return attn, attn_weights + + @staticmethod + def _append_prev_key_padding_mask( + key_padding_mask: Optional[Tensor], + prev_key_padding_mask: Optional[Tensor], + batch_size: int, + src_len: int, + static_kv: bool, + ) -> Optional[Tensor]: + # saved key padding masks have shape (bsz, seq_len) + if prev_key_padding_mask is not None and static_kv: + new_key_padding_mask = prev_key_padding_mask + elif prev_key_padding_mask is not None and key_padding_mask is not None: + new_key_padding_mask = torch.cat( + [prev_key_padding_mask.float(), key_padding_mask.float()], dim=1 + ) + # During incremental decoding, as the padding token enters and + # leaves the frame, there will be a time when prev or current + # is None + elif prev_key_padding_mask is not None: + if src_len > prev_key_padding_mask.size(1): + filler = torch.zeros( + (batch_size, src_len - prev_key_padding_mask.size(1)), + device=prev_key_padding_mask.device, + ) + new_key_padding_mask = torch.cat( + [prev_key_padding_mask.float(), filler.float()], dim=1 + ) + else: + new_key_padding_mask = prev_key_padding_mask.float() + elif key_padding_mask is not None: + if src_len > key_padding_mask.size(1): + filler = torch.zeros( + (batch_size, src_len - key_padding_mask.size(1)), + device=key_padding_mask.device, + ) + new_key_padding_mask = torch.cat( + [filler.float(), key_padding_mask.float()], dim=1 + ) + else: + new_key_padding_mask = key_padding_mask.float() + else: + new_key_padding_mask = prev_key_padding_mask + return new_key_padding_mask + + @torch.jit.export + def reorder_incremental_state( + self, + incremental_state: Dict[str, Dict[str, Optional[Tensor]]], + new_order: Tensor, + ): + """Reorder buffered internal state (for incremental generation).""" + input_buffer = self._get_input_buffer(incremental_state) + if input_buffer is not None: + for k in input_buffer.keys(): + input_buffer_k = input_buffer[k] + if input_buffer_k is not None: + if self.encoder_decoder_attention: + if input_buffer_k.size(0) * self.beam_size == new_order.size(0): + return incremental_state + elif self.beam_size > 1: + input_buffer[k] = input_buffer_k.index_select( + 0, + new_order.reshape(-1, self.beam_size)[:, 0] + // self.beam_size, + ) + else: + input_buffer[k] = input_buffer_k.index_select(0, new_order) + else: + input_buffer[k] = input_buffer_k.index_select(0, new_order) + incremental_state = self._set_input_buffer(incremental_state, input_buffer) + return incremental_state + + def set_beam_size(self, beam_size): + """Used for effiecient beamable enc-dec attention""" + self.beam_size = beam_size + + def _get_input_buffer( + self, incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] + ) -> Dict[str, Optional[Tensor]]: + result = self.get_incremental_state(incremental_state, "attn_state") + if result is not None: + return result + else: + empty_result: Dict[str, Optional[Tensor]] = {} + return empty_result + + def _set_input_buffer( + self, + incremental_state: Dict[str, Dict[str, Optional[Tensor]]], + buffer: Dict[str, Optional[Tensor]], + ): + return self.set_incremental_state(incremental_state, "attn_state", buffer) + + def apply_sparse_mask(self, attn_weights, tgt_len: int, src_len: int, bsz: int): + return attn_weights + + def upgrade_state_dict_named(self, state_dict, name): + prefix = name + "." if name != "" else "" + items_to_add = {} + keys_to_remove = [] + for k in state_dict.keys(): + if k.endswith(prefix + "in_proj_weight"): + # in_proj_weight used to be q + k + v with same dimensions + dim = int(state_dict[k].shape[0] / 3) + items_to_add[prefix + "q_proj.weight"] = state_dict[k][:dim] + items_to_add[prefix + "k_proj.weight"] = state_dict[k][dim : 2 * dim] + items_to_add[prefix + "v_proj.weight"] = state_dict[k][2 * dim :] + + keys_to_remove.append(k) + + k_bias = prefix + "in_proj_bias" + if k_bias in state_dict.keys(): + dim = int(state_dict[k].shape[0] / 3) + items_to_add[prefix + "q_proj.bias"] = state_dict[k_bias][:dim] + items_to_add[prefix + "k_proj.bias"] = state_dict[k_bias][ + dim : 2 * dim + ] + items_to_add[prefix + "v_proj.bias"] = state_dict[k_bias][2 * dim :] + + keys_to_remove.append(prefix + "in_proj_bias") + + for k in keys_to_remove: + del state_dict[k] + + for key, value in items_to_add.items(): + state_dict[key] = value diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/positional_embedding.py b/PyTorch/NLP/new-Transformer/fairseq/modules/positional_embedding.py new file mode 100644 index 00000000..97cd474b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/positional_embedding.py @@ -0,0 +1,35 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn as nn + +from .learned_positional_embedding import LearnedPositionalEmbedding +from .sinusoidal_positional_embedding import SinusoidalPositionalEmbedding + + +def PositionalEmbedding( + num_embeddings: int, + embedding_dim: int, + padding_idx: int, + learned: bool = False, +): + if learned: + # if padding_idx is specified then offset the embedding ids by + # this index and adjust num_embeddings appropriately + # TODO: The right place for this offset would be inside + # LearnedPositionalEmbedding. Move this there for a cleaner implementation. + if padding_idx is not None: + num_embeddings = num_embeddings + padding_idx + 1 + m = LearnedPositionalEmbedding(num_embeddings, embedding_dim, padding_idx) + nn.init.normal_(m.weight, mean=0, std=embedding_dim**-0.5) + if padding_idx is not None: + nn.init.constant_(m.weight[padding_idx], 0) + else: + m = SinusoidalPositionalEmbedding( + embedding_dim, + padding_idx, + init_size=num_embeddings + padding_idx + 1, + ) + return m diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/positional_encoding.py b/PyTorch/NLP/new-Transformer/fairseq/modules/positional_encoding.py new file mode 100644 index 00000000..67f63535 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/positional_encoding.py @@ -0,0 +1,129 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn as nn +import math +import torch + + +class PositionalEncoding(nn.Module): + """Positional encoding. + + Args: + d_model: Embedding dimension. + dropout_rate: Dropout rate. + max_len: Maximum input length. + reverse: Whether to reverse the input position. + """ + + def __init__(self, d_model, dropout_rate, max_len=5000, reverse=False): + """Construct an PositionalEncoding object.""" + super(PositionalEncoding, self).__init__() + self.d_model = d_model + self.reverse = reverse + self.xscale = math.sqrt(self.d_model) + self.dropout = nn.Dropout(p=dropout_rate) + self.pe = None + self.extend_pe(torch.tensor(0.0).expand(1, max_len)) + + def extend_pe(self, x): + """Reset the positional encodings.""" + if self.pe is not None: + if self.pe.size(1) >= x.size(1): + if self.pe.dtype != x.dtype or self.pe.device != x.device: + self.pe = self.pe.to(dtype=x.dtype, device=x.device) + return + pe = torch.zeros(x.size(1), self.d_model) + if self.reverse: + position = torch.arange( + x.size(1) - 1, -1, -1.0, dtype=torch.float32 + ).unsqueeze(1) + else: + position = torch.arange(0, x.size(1), dtype=torch.float32).unsqueeze(1) + div_term = torch.exp( + torch.arange(0, self.d_model, 2, dtype=torch.float32) + * -(math.log(10000.0) / self.d_model) + ) + pe[:, 0::2] = torch.sin(position * div_term) + pe[:, 1::2] = torch.cos(position * div_term) + pe = pe.unsqueeze(0) + self.pe = pe.to(device=x.device, dtype=x.dtype) + + def forward(self, x: torch.Tensor): + """Add positional encoding. + Args: + x (torch.Tensor): Input tensor B X T X C + Returns: + torch.Tensor: Encoded tensor B X T X C + """ + self.extend_pe(x) + x = x * self.xscale + self.pe[:, : x.size(1)] + return self.dropout(x) + + +class RelPositionalEncoding(nn.Module): + """Relative positional encoding module (new implementation). + + Args: + d_model: Embedding dimension. + dropout_rate: Dropout rate. + max_len: Maximum input length. + """ + + def __init__(self, max_len, d_model): + """Construct an PositionalEncoding object.""" + super(RelPositionalEncoding, self).__init__() + self.d_model = d_model + self.pe = None + self.extend_pe(torch.tensor(0.0).expand(1, max_len)) + + def extend_pe(self, x): + """Reset the positional encodings.""" + if self.pe is not None: + # self.pe contains both positive and negative parts + # the length of self.pe is 2 * input_len - 1 + if self.pe.size(1) >= x.size(1) * 2 - 1: + if self.pe.dtype != x.dtype or self.pe.device != x.device: + self.pe = self.pe.to(dtype=x.dtype, device=x.device) + return + # Suppose `i` means to the position of query vecotr and `j` means the + # position of key vector. We use position relative positions when keys + # are to the left (i>j) and negative relative positions otherwise (i 0: + # given an empty cluster, find most populated cluster and split it into two + k = random.choice(list(empty_clusters)) + m = counts.most_common(1)[0][0] + e = torch.randn_like(self.centroids[m]) * self.eps + self.centroids[k] = self.centroids[m].clone() + self.centroids[k] += e + self.centroids[m] -= e + + # recompute assignments + distances = self.compute_distances() # (n_centroids x out_features) + self.assignments = torch.argmin(distances, dim=0) # (out_features) + + # check for empty clusters + counts = Counter(map(lambda x: x.item(), self.assignments)) + empty_clusters = set(range(self.n_centroids)) - set(counts.keys()) + + # increment tentatives + if tentatives == self.max_tentatives: + logging.info( + f"Could not resolve all empty clusters, {len(empty_clusters)} remaining" + ) + raise EmptyClusterResolveError + tentatives += 1 + + return n_empty_clusters + + def compute_distances(self): + """ + For every centroid m, computes + + ||M - m[None, :]||_2 + + Remarks: + - We rely on PyTorch's broadcasting to speed up computations + and reduce the memory overhead + - Without chunking, the sizes in the broadcasting are modified as: + (n_centroids x n_samples x out_features) -> (n_centroids x out_features) + - The broadcasting computation is automatically chunked so that + the tensors fit into the memory of the GPU + """ + + nb_centroids_chunks = 1 + + while True: + try: + return torch.cat( + [ + (self.W[None, :, :] - centroids_c[:, :, None]).norm(p=2, dim=1) + for centroids_c in self.centroids.chunk( + nb_centroids_chunks, dim=0 + ) + ], + dim=0, + ) + except RuntimeError: + nb_centroids_chunks *= 2 + + def assign(self): + """ + Assigns each column of W to its closest centroid, thus essentially + performing the E-step in train(). + + Remarks: + - The function must be called after train() or after loading + centroids using self.load(), otherwise it will return empty tensors + """ + + distances = self.compute_distances() # (n_centroids x out_features) + self.assignments = torch.argmin(distances, dim=0) # (out_features) + + def save(self, path, layer): + """ + Saves centroids and assignments. + + Args: + - path: folder used to save centroids and assignments + """ + + torch.save(self.centroids, os.path.join(path, "{}_centroids.pth".format(layer))) + torch.save( + self.assignments, os.path.join(path, "{}_assignments.pth".format(layer)) + ) + torch.save(self.objective, os.path.join(path, "{}_objective.pth".format(layer))) + + def load(self, path, layer): + """ + Loads centroids and assignments from a given path + + Args: + - path: folder use to load centroids and assignments + """ + + self.centroids = torch.load( + os.path.join(path, "{}_centroids.pth".format(layer)) + ) + self.assignments = torch.load( + os.path.join(path, "{}_assignments.pth".format(layer)) + ) + self.objective = torch.load( + os.path.join(path, "{}_objective.pth".format(layer)) + ) + + +class EmptyClusterResolveError(Exception): + pass diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/__init__.py new file mode 100644 index 00000000..b67c8e8a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/__init__.py @@ -0,0 +1,8 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .qconv import PQConv2d # NOQA +from .qemb import PQEmbedding # NOQA +from .qlinear import PQLinear # NOQA diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qconv.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qconv.py new file mode 100644 index 00000000..d15ec192 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qconv.py @@ -0,0 +1,115 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +import torch +import torch.nn as nn +import torch.nn.functional as F +from torch.nn.modules.utils import _pair + + +class PQConv2d(nn.Module): + """ + Quantized counterpart of nn.Conv2d module. Stores the centroid, the assignments + and the non-quantized biases. The full weight is re-instantiated at each forward + pass and autograd automatically computes the gradients with respect to the + centroids. + + Args: + - centroids: centroids of size n_centroids x block_size + - assignments: assignments of the centroids to the subvectors + of size self.out_channels x n_blocks + - bias: the non-quantized bias, must be either torch.Tensor or None + + Remarks: + - We refer the reader to the official documentation of the nn.Conv2d module + for the other arguments and the behavior of the module. + - Performance tests on GPU show that this implementation is 10% slower than + the non-quantized nn.Conv2d module for a standard training loop. + - During the backward, the gradients are averaged by cluster and not summed. + This explains the hook registered to the centroids. + """ + + def __init__( + self, + centroids, + assignments, + bias, + in_channels, + out_channels, + kernel_size, + stride=1, + padding=0, + dilation=1, + groups=1, + padding_mode="zeros", + ): + super(PQConv2d, self).__init__() + self.block_size = centroids.size(1) + self.n_centroids = centroids.size(0) + self.in_channels = in_channels + self.out_channels = out_channels + self.kernel_size = _pair(kernel_size) + self.stride = _pair(stride) + self.padding = _pair(padding) + self.dilation = _pair(dilation) + self.groups = groups + self.padding_mode = padding_mode + # check compatibility + if in_channels // groups * np.prod(self.kernel_size) % self.block_size != 0: + raise ValueError("Wrong PQ sizes") + if len(assignments) % out_channels != 0: + raise ValueError("Wrong PQ sizes") + if in_channels % groups != 0: + raise ValueError("in_channels must be divisible by groups") + if out_channels % groups != 0: + raise ValueError("out_channels must be divisible by groups") + # define parameters + self.centroids = nn.Parameter(centroids, requires_grad=True) + self.register_buffer("assignments", assignments) + self.register_buffer("counts", torch.bincount(assignments).type_as(centroids)) + if bias is not None: + self.bias = nn.Parameter(bias) + else: + self.register_parameter("bias", None) + # register hook for averaging gradients per centroids instead of summing + self.centroids.register_hook(lambda x: x / self.counts[:, None]) + + @property + def weight(self): + return ( + self.centroids[self.assignments] + .reshape(-1, self.out_channels, self.block_size) + .permute(1, 0, 2) + .reshape( + self.out_channels, self.in_channels // self.groups, *self.kernel_size + ) + ) + + def forward(self, x): + return F.conv2d( + x, + self.weight, + self.bias, + self.stride, + self.padding, + self.dilation, + self.groups, + ) + + def extra_repr(self): + s = "{in_channels}, {out_channels}, kernel_size={kernel_size}, stride={stride}" + if self.padding != (0,) * len(self.padding): + s += ", padding={padding}" + if self.dilation != (1,) * len(self.dilation): + s += ", dilation={dilation}" + if self.groups != 1: + s += ", groups={groups}" + if self.bias is None: + s += ", bias=False" + if self.padding_mode != "zeros": + s += ", padding_mode={padding_mode}" + s += ", n_centroids={n_centroids}, block_size={block_size}" + return s.format(**self.__dict__) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qemb.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qemb.py new file mode 100644 index 00000000..3a74ad3c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qemb.py @@ -0,0 +1,107 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F + + +class PQEmbedding(nn.Module): + """ + Quantized counterpart of nn.Embedding module. Stores the centroids and + the assignments. The full weight is re-instantiated at each forward + pass. + + Args: + - centroids: centroids of size n_centroids x block_size + - assignments: assignments of the centroids to the subvectors + of size self.out_features x n_blocks + - bias: the non-quantized bias + + Remarks: + - We refer the reader to the official documentation of the nn.Embedding module + for the other arguments and the behavior of the module + - Performance tests on GPU show that this implementation is 10% slower than + the non-quantized nn.Embedding module for a standard training loop. + """ + + def __init__( + self, + centroids, + assignments, + num_embeddings, + embedding_dim, + padding_idx=None, + max_norm=None, + norm_type=2.0, + scale_grad_by_freq=False, + sparse=False, + _weight=None, + ): + super(PQEmbedding, self).__init__() + self.block_size = centroids.size(1) + self.n_centroids = centroids.size(0) + self.num_embeddings = num_embeddings + self.embedding_dim = embedding_dim + if padding_idx is not None: + if padding_idx > 0: + assert ( + padding_idx < self.num_embeddings + ), "Padding_idx must be within num_embeddings" + elif padding_idx < 0: + assert ( + padding_idx >= -self.num_embeddings + ), "Padding_idx must be within num_embeddings" + padding_idx = self.num_embeddings + padding_idx + self.padding_idx = padding_idx + self.max_norm = max_norm + self.norm_type = norm_type + self.scale_grad_by_freq = scale_grad_by_freq + self.sparse = sparse + # check compatibility + if self.embedding_dim % self.block_size != 0: + raise ValueError("Wrong PQ sizes") + if len(assignments) % self.num_embeddings != 0: + raise ValueError("Wrong PQ sizes") + # define parameters + self.centroids = nn.Parameter(centroids, requires_grad=True) + self.register_buffer("assignments", assignments) + self.register_buffer("counts", torch.bincount(assignments).type_as(centroids)) + + @property + def weight(self): + return ( + self.centroids[self.assignments] + .reshape(-1, self.num_embeddings, self.block_size) + .permute(1, 0, 2) + .flatten(1, 2) + ) + + def forward(self, input): + return F.embedding( + input, + self.weight, + self.padding_idx, + self.max_norm, + self.norm_type, + self.scale_grad_by_freq, + self.sparse, + ) + + def extra_repr(self): + s = "{num_embeddings}, {embedding_dim}" + if self.padding_idx is not None: + s += ", padding_idx={padding_idx}" + if self.max_norm is not None: + s += ", max_norm={max_norm}" + if self.norm_type != 2: + s += ", norm_type={norm_type}" + if self.scale_grad_by_freq is not False: + s += ", scale_grad_by_freq={scale_grad_by_freq}" + if self.sparse is not False: + s += ", sparse=True" + s += ", n_centroids={n_centroids}, block_size={block_size}" + + return s.format(**self.__dict__) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qlinear.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qlinear.py new file mode 100644 index 00000000..9bdd25a8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/modules/qlinear.py @@ -0,0 +1,71 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F + + +class PQLinear(nn.Module): + """ + Quantized counterpart of nn.Linear module. Stores the centroid, the assignments + and the non-quantized biases. The full weight is re-instantiated at each forward + pass. + + Args: + - centroids: centroids of size n_centroids x block_size + - assignments: assignments of the centroids to the subvectors + of size self.out_features x n_blocks + - bias: the non-quantized bias + + Remarks: + - We refer the reader to the official documentation of the nn.Linear module + for the other arguments and the behavior of the module + - Performance tests on GPU show that this implementation is 15% slower than + the non-quantized nn.Linear module for a standard training loop. + """ + + def __init__(self, centroids, assignments, bias, in_features, out_features): + super(PQLinear, self).__init__() + self.block_size = centroids.size(1) + self.n_centroids = centroids.size(0) + self.in_features = in_features + self.out_features = out_features + # check compatibility + if self.in_features % self.block_size != 0: + raise ValueError("Wrong PQ sizes") + if len(assignments) % self.out_features != 0: + raise ValueError("Wrong PQ sizes") + # define parameters + self.centroids = nn.Parameter(centroids, requires_grad=True) + self.register_buffer("assignments", assignments) + self.register_buffer("counts", torch.bincount(assignments).type_as(centroids)) + if bias is not None: + self.bias = nn.Parameter(bias) + else: + self.register_parameter("bias", None) + + @property + def weight(self): + return ( + self.centroids[self.assignments] + .reshape(-1, self.out_features, self.block_size) + .permute(1, 0, 2) + .flatten(1, 2) + ) + + def forward(self, x): + return F.linear( + x, + self.weight, + self.bias, + ) + + def extra_repr(self): + return f"in_features={self.in_features},\ + out_features={self.out_features},\ + n_centroids={self.n_centroids},\ + block_size={self.block_size},\ + bias={self.bias is not None}" diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/pq.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/pq.py new file mode 100644 index 00000000..eddc2eb3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/pq.py @@ -0,0 +1,128 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .em import EM, EmptyClusterResolveError + + +class PQ(EM): + """ + Quantizes the layer weights W with the standard Product Quantization + technique. This learns a codebook of codewords or centroids of size + block_size from W. For further reference on using PQ to quantize + neural networks, see "And the Bit Goes Down: Revisiting the Quantization + of Neural Networks", Stock et al., ICLR 2020. + + PQ is performed in two steps: + (1) The matrix W (weights or fully-connected or convolutional layer) + is reshaped to (block_size, -1). + - If W is fully-connected (2D), its columns are split into + blocks of size block_size. + - If W is convolutional (4D), its filters are split along the + spatial dimension. + (2) We apply the standard EM/k-means algorithm to the resulting reshaped matrix. + + Args: + - W: weight matrix to quantize of size (in_features x out_features) + - block_size: size of the blocks (subvectors) + - n_centroids: number of centroids + - n_iter: number of k-means iterations + - eps: for cluster reassignment when an empty cluster is found + - max_tentatives for cluster reassignment when an empty cluster is found + - verbose: print information after each iteration + + Remarks: + - block_size be compatible with the shape of W + """ + + def __init__( + self, + W, + block_size, + n_centroids=256, + n_iter=20, + eps=1e-6, + max_tentatives=30, + verbose=True, + ): + self.block_size = block_size + W_reshaped = self._reshape(W) + super(PQ, self).__init__( + W_reshaped, + n_centroids=n_centroids, + n_iter=n_iter, + eps=eps, + max_tentatives=max_tentatives, + verbose=verbose, + ) + + def _reshape(self, W): + """ + Reshapes the matrix W as expained in step (1). + """ + + # fully connected: by convention the weight has size out_features x in_features + if len(W.size()) == 2: + self.out_features, self.in_features = W.size() + assert ( + self.in_features % self.block_size == 0 + ), "Linear: n_blocks must be a multiple of in_features" + return ( + W.reshape(self.out_features, -1, self.block_size) + .permute(2, 1, 0) + .flatten(1, 2) + ) + + # convolutional: we reshape along the spatial dimension + elif len(W.size()) == 4: + self.out_channels, self.in_channels, self.k_h, self.k_w = W.size() + assert ( + self.in_channels * self.k_h * self.k_w + ) % self.block_size == 0, ( + "Conv2d: n_blocks must be a multiple of in_channels * k_h * k_w" + ) + return ( + W.reshape(self.out_channels, -1, self.block_size) + .permute(2, 1, 0) + .flatten(1, 2) + ) + # not implemented + else: + raise NotImplementedError(W.size()) + + def encode(self): + """ + Performs self.n_iter EM steps. + """ + + self.initialize_centroids() + for i in range(self.n_iter): + try: + self.step(i) + except EmptyClusterResolveError: + break + + def decode(self): + """ + Returns the encoded full weight matrix. Must be called after + the encode function. + """ + + # fully connected case + if "k_h" not in self.__dict__: + return ( + self.centroids[self.assignments] + .reshape(-1, self.out_features, self.block_size) + .permute(1, 0, 2) + .flatten(1, 2) + ) + + # convolutional case + else: + return ( + self.centroids[self.assignments] + .reshape(-1, self.out_channels, self.block_size) + .permute(1, 0, 2) + .reshape(self.out_channels, self.in_channels, self.k_h, self.k_w) + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/utils.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/utils.py new file mode 100644 index 00000000..eceeef8b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/pq/utils.py @@ -0,0 +1,376 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import re +from operator import attrgetter, itemgetter +import torch +import numpy as np +import torch.distributed as dist +import torch.nn as nn + +from .modules import PQConv2d, PQEmbedding, PQLinear +from .pq import PQ + + +def quantize_model_( + model, + size_tracker, + layers_to_quantize, + block_sizes_config, + n_centroids_config, + step=0, + n_iter=15, + eps=1e-6, + max_tentatives=100, + remove_weights=False, + verbose=True, + state_dict=None, +): + """ + Quantize a model in-place by stages. All the targeted + layers are replaced by their quantized counterpart, + and the model is ready for the finetuning of the + centroids in a standard training loop (no modifications + required). Note that we do not quantize biases. + + Args: + - model: a nn.Module + - size_tracker: useful for tracking quatization statistics + - layers_to_quantize: a list containing regexps for + filtering the layers to quantize at each stage according + to their name (as in model.named_parameters()) + - block_sizes_config: dict like + { + 'Conv2d': ('kernel_size', {'(3, 3)': 9, '(1, 1)': 4}), + 'Linear': ('in_features', {'*': 8}) + } + For instance, all conv2d layers with kernel size 3x3 have + a block size of 9 and all Linear layers are quantized with + a block size of 8, irrespective of their size. + - n_centroids_config: dict like + { + 'Conv2d': ('kernel_size', {'*': 256}), + 'Linear': ('in_features', {'*': 256}) + } + For instance, all conv2d layers are quantized with 256 centroids + - step: the layers to quantize inplace corresponding + to layers_to_quantize[step] + """ + + quantized_layers = get_layers( + model, layers_to_quantize[step], remove_weights=remove_weights + ) + + for layer in quantized_layers: + + # book-keeping + is_master_process = (not dist.is_initialized()) or ( + dist.is_initialized() and dist.get_rank() == 0 + ) + verbose = verbose and is_master_process + + # get block size and centroids + module = attrgetter(layer)(model) + block_size = get_param(module, layer, block_sizes_config) + n_centroids = get_param(module, layer, n_centroids_config) + if verbose: + logging.info( + f"Quantizing layer {layer} with block size {block_size} and {n_centroids} centroids" + ) + + # quantize layer + weight = module.weight.data.clone() + is_bias = "bias" in [x[0] for x in module.named_parameters()] + bias = module.bias.data.clone() if is_bias else None + quantizer = PQ( + weight, + block_size, + n_centroids=n_centroids, + n_iter=n_iter, + eps=eps, + max_tentatives=max_tentatives, + verbose=verbose, + ) + + # quantization performed on all GPUs with same seed + quantizer.encode() + centroids = quantizer.centroids.contiguous() + assignments = quantizer.assignments.contiguous() + + # If n_iter = 0 and state_dict is provided, then + # we initialize random assignments and centroids to + # random values of the appropriate dimensions + # because the quantized model parameters will + # overwritten by the state_dict later on. + if n_iter == 0 and state_dict: + # Initialize random centroids of the correct size + centroids = torch.rand(centroids.size()) + centroids.cuda() + # Get counts and assignment keys from layer in loaded checkpoint. + counts_key = layer + "." + "counts" + assignment_key = layer + "." + "assignments" + # Get number of different bins to include. + counts = list(state_dict[counts_key].shape)[0] + print(layer) + print(state_dict[counts_key]) + print(counts) + # Initialize random assignments of the correct size + # with an appropriate number of bins. + num_assignments = list(state_dict[assignment_key].shape)[0] + num_extra = num_assignments - counts + print(num_assignments) + print(num_extra) + assignments_bins = torch.arange(counts) + assignments_rand = torch.randint(0, counts - 1, (num_extra,)) + assignments = torch.cat((assignments_bins, assignments_rand), 0) + # assignments = assignments.type(torch.IntTensor) + assignments.cuda() + print("assignments") + print(assignments) + + # broadcast results to make sure weights are up-to-date + if dist.is_initialized(): + dist.broadcast(centroids, 0) + dist.broadcast(assignments, 0) + + # instantiate the quantized counterpart + if isinstance(module, nn.Linear): + out_features, in_features = map( + lambda k: module.__dict__[k], ["out_features", "in_features"] + ) + quantized_module = PQLinear( + centroids, assignments, bias, in_features, out_features + ) + elif isinstance(module, nn.Embedding): + num_embeddings, embedding_dim = map( + lambda k: module.__dict__[k], ["num_embeddings", "embedding_dim"] + ) + quantized_module = PQEmbedding( + centroids, assignments, num_embeddings, embedding_dim + ) + elif isinstance(module, nn.Conv2d): + out_channels, in_channels, kernel_size = map( + lambda k: module.__dict__[k], + ["out_channels", "in_channels", "kernel_size"], + ) + stride, padding, dilation, groups, padding_mode = map( + lambda k: module.__dict__[k], + ["stride", "padding", "dilation", "groups", "padding_mode"], + ) + + quantized_module = PQConv2d( + centroids, + assignments, + bias, + in_channels, + out_channels, + kernel_size, + stride=stride, + padding=padding, + dilation=dilation, + groups=groups, + padding_mode=padding_mode, + ) + else: + raise ValueError(f"Module {module} not yet supported for quantization") + + # replace layer by its quantized counterpart + attrsetter(layer)(model, quantized_module) + + # update statistics + size_tracker.update(weight, block_size, n_centroids) + + # return name of quantized layers + return quantized_layers + + +def get_layers(model, filter_regexp, remove_weights=False): + """ + Filters out the layers according to a regexp. Note that + we omit biases. + + Args: + - model: a nn.Module + - filter_regexp: a regexp to filter the layers to keep + according to their name in model.named_parameters(). + For instance, the regexp: + + down_layers\\.[123456]\\.(conv[12]|identity\\.conv)) + + is keeping blocks down_layers from 1 to 6, and inside + each block is keeping conv1, conv2 and identity.conv. + + Remarks: + - We add (module\\.)? at the beginning of the regexp to + account for the possible use of nn.parallel.DataParallel + """ + + # get all parameter names + all_layers = map(itemgetter(0), model.named_parameters()) + + # remove biases + all_layers = filter(lambda x: "bias" not in x, all_layers) + + # remove .weight in all other names (or .weight_orig is spectral norm) + all_layers = map(lambda x: x.replace(".weight_orig", ""), all_layers) + # remove weights indicates whether the weights extension should be removed, in addition to + # weight_orig and weight extension on names + if remove_weights: + all_layers = map(lambda x: x.replace(".weights", ""), all_layers) + all_layers = map(lambda x: x.replace(".weight", ""), all_layers) + + # return filtered layers + filter_regexp = "(module\\.)?" + "(" + filter_regexp + ")" + r = re.compile(filter_regexp) + + return list(filter(r.match, all_layers)) + + +def get_param(module, layer_name, param_config): + """ + Given a quantization configuration, get the right parameter + for the module to be quantized. + + Args: + - module: a nn.Module + - layer_name: the name of the layer + - param_config: a dict like + { + 'Conv2d': ('kernel_size', {'(3, 3)': 9, '(1, 1)': 4}), + 'Linear': ('in_features', {'*': 8}) + } + For instance, all conv2d layers with kernel size 3x3 have + a block size of 9 and all Linear layers are quantized with + a block size of 8, irrespective of their size. + + Remarks: + - if 'fuzzy_name' is passed as a parameter, layers whose layer_name + include 'fuzzy_name' will be assigned the given parameter. + In the following example, conv.expand layers will have a block + size of 9 while conv.reduce will have a block size of 4 and all + other layers will have a block size of 2. + { + 'Conv2d': ('fuzzy_name', {'expand': 9, 'reduce': 4, '*': 2}), + 'Linear': ('fuzzy_name', {'classifier': 8, 'projection': 4}) + } + + """ + + layer_type = module.__class__.__name__ + + if layer_type not in param_config: + raise KeyError(f"Layer type {layer_type} not in config for layer {module}") + + feature, params = param_config[module.__class__.__name__] + + if feature != "fuzzy_name": + feature_value = str(getattr(module, feature)) + if feature_value not in params: + if "*" in params: + feature_value = "*" + else: + raise KeyError( + f"{feature}={feature_value} not in config for layer {module}" + ) + else: + feature_values = [name for name in params if name in layer_name] + if len(feature_values) == 0: + if "*" in params: + feature_value = "*" + else: + raise KeyError(f"name={layer_name} not in config for {module}") + else: + feature_value = feature_values[0] + + return params[feature_value] + + +class SizeTracker(object): + """ + Class to keep track of the compressed network size with iPQ. + + Args: + - model: a nn.Module + + Remarks: + - The compressed size is the sum of three components + for each layer in the network: + (1) Storing the centroids given by iPQ in fp16 + (2) Storing the assignments of the blocks in int8 + (3) Storing all non-compressed elements such as biases + - This cost in only valid if we use 256 centroids (then + indexing can indeed by done with int8). + """ + + def __init__(self, model): + self.model = model + self.size_non_compressed_model = self.compute_size() + self.size_non_quantized = self.size_non_compressed_model + self.size_index = 0 + self.size_centroids = 0 + self.n_quantized_layers = 0 + + def compute_size(self): + """ + Computes the size of the model (in MB). + """ + + res = 0 + for _, p in self.model.named_parameters(): + res += p.numel() + return res * 4 / 1024 / 1024 + + def update(self, W, block_size, n_centroids): + """ + Updates the running statistics when quantizing a new layer. + """ + + # bits per weights + bits_per_weight = np.log2(n_centroids) / block_size + self.n_quantized_layers += 1 + + # size of indexing the subvectors of size block_size (in MB) + size_index_layer = bits_per_weight * W.numel() / 8 / 1024 / 1024 + self.size_index += size_index_layer + + # size of the centroids stored in float16 (in MB) + size_centroids_layer = n_centroids * block_size * 2 / 1024 / 1024 + self.size_centroids += size_centroids_layer + + # size of non-compressed layers, e.g. LayerNorms or biases (in MB) + size_uncompressed_layer = W.numel() * 4 / 1024 / 1024 + self.size_non_quantized -= size_uncompressed_layer + + def __repr__(self): + size_compressed = ( + self.size_index + self.size_centroids + self.size_non_quantized + ) + compression_ratio = self.size_non_compressed_model / size_compressed # NOQA + return ( + f"Non-compressed model size: {self.size_non_compressed_model:.2f} MB. " + f"After quantizing {self.n_quantized_layers} layers, size " + f"(indexing + centroids + other): {self.size_index:.2f} MB + " + f"{self.size_centroids:.2f} MB + {self.size_non_quantized:.2f} MB = " + f"{size_compressed:.2f} MB, compression ratio: {compression_ratio:.2f}x" + ) + + +def attrsetter(*items): + def resolve_attr(obj, attr): + attrs = attr.split(".") + head = attrs[:-1] + tail = attrs[-1] + + for name in head: + obj = getattr(obj, name) + return obj, tail + + def g(obj, val): + for attr in items: + resolved_obj, resolved_attr = resolve_attr(obj, attr) + setattr(resolved_obj, resolved_attr, val) + + return g diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/quantization_options.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/quantization_options.py new file mode 100644 index 00000000..b46d682c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/quantization_options.py @@ -0,0 +1,44 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +def parse_config_yaml(yaml_data): + # Initialize to default options. + quantization_options = { + "n_centroids": { + "Linear": ["in_features", {"*": 256}], + "Embedding": ["embedding_dim", {"*": 256}], + }, + "block_sizes": { + "Linear": ["fuzzy_name", {"fc": 8, "attn": 4, "emb": 4}], + "Embedding": ["fuzzy_name", {"emb": 8}], + }, + "layers_to_quantize": [ + "decoder\\.layers\\.\\d+\\.fc[12]", + "decoder\\.embed_tokens\\.embeddings\\.[012]\\.[01]", + "decoder\\.layers\\.\\d+\\.self_attn\\.(k_proj|v_proj|q_proj|out_proj)", + ], + } + + if "n_centroids" in yaml_data: + quantization_options["n_centroids"] = { + layer: convert_yaml_to_tuple(layer_data) + for layer, layer_data in yaml_data["n_centroids"].items() + } + if "block_sizes" in yaml_data: + quantization_options["block_sizes"] = { + layer: convert_yaml_to_tuple(layer_data) + for layer, layer_data in yaml_data["block_sizes"].items() + } + if "layers_to_quantize" in yaml_data: + quantization_options["layers_to_quantize"] = yaml_data["layers_to_quantize"] + + return quantization_options + + +def convert_yaml_to_tuple(yaml_dictionary): + """Converts a yaml dictionary with two keys: `key` and `value` into a two + argument tuple of those values.""" + return (yaml_dictionary["key"], yaml_dictionary["value"]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/__init__.py new file mode 100644 index 00000000..143834f3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/__init__.py @@ -0,0 +1,6 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .utils import quantize_model_ # NOQA diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/__init__.py new file mode 100644 index 00000000..8031d9cd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/__init__.py @@ -0,0 +1,9 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from .qact import ActivationQuantizer # NOQA +from .qconv import IntConv2d # NOQA +from .qemb import IntEmbedding # NOQA +from .qlinear import IntLinear # NOQA diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qact.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qact.py new file mode 100644 index 00000000..b362c30d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qact.py @@ -0,0 +1,88 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +from ..ops import emulate_int + + +class ActivationQuantizer: + """ + Fake scalar quantization of the activations using a forward hook. + + Args: + - module. a nn.Module for which we quantize the *post-activations* + - p: proportion of activations to quantize, set by default to 1 + - update_step: to recompute quantization parameters + - bits: number of bits for quantization + - method: choose among {"tensor", "histogram", "channel"} + - clamp_threshold: to prevent gradients overflow + + Remarks: + - Parameters scale and zero_point are recomputed every update_step + forward pass to reduce the overhead + - For the list of quantization methods and number of bits, see ops.py + - To remove the hook from the module, simply call self.handle.remove() + - At test time, the activations are fully quantized + - We use the straight-through estimator so that the gradients + back-propagate nicely in the network, this is implemented with + the detach() trick + - The activations are hard-clamped in [-clamp_threshold, clamp_threshold] + to prevent overflow during the backward pass + """ + + def __init__( + self, + module, + p=1, + update_step=1000, + bits=8, + method="histogram", + clamp_threshold=5, + ): + self.module = module + self.p = p + self.update_step = update_step + self.counter = 0 + self.bits = bits + self.method = method + self.clamp_threshold = clamp_threshold + self.handle = None + self.register_hook() + + def register_hook(self): + # forward hook + def quantize_hook(module, x, y): + + # update parameters every 1000 iterations + if self.counter % self.update_step == 0: + self.scale = None + self.zero_point = None + self.counter += 1 + + # train with QuantNoise and evaluate the fully quantized network + p = self.p if self.module.training else 1 + + # quantize activations + y_q, self.scale, self.zero_point = emulate_int( + y.detach(), + bits=self.bits, + method=self.method, + scale=self.scale, + zero_point=self.zero_point, + ) + + # mask to apply noise + mask = torch.zeros_like(y) + mask.bernoulli_(1 - p) + noise = (y_q - y).masked_fill(mask.bool(), 0) + + # using straight-through estimator (STE) + clamp_low = -self.scale * self.zero_point + clamp_high = self.scale * (2**self.bits - 1 - self.zero_point) + return torch.clamp(y, clamp_low.item(), clamp_high.item()) + noise.detach() + + # register hook + self.handle = self.module.register_forward_hook(quantize_hook) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qconv.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qconv.py new file mode 100644 index 00000000..29744744 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qconv.py @@ -0,0 +1,149 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn.functional as F +from torch.nn.modules.conv import _ConvNd +from torch.nn.modules.utils import _pair + +from ..ops import emulate_int + + +class IntConv2d(_ConvNd): + """ + Quantized counterpart of the nn.Conv2d module that applies QuantNoise during training. + + Args: + - standard nn.Conv2d parameters + - p: amount of noise to inject (0 = no quantization, 1 = quantize all the weights) + - bits: number of bits + - method: choose among {"tensor", "histogram", "channel"} + - update_step: recompute scale and zero_point every update_steps iterations + + Remarks: + - We use the straight-thgourh estimator so that the gradients + back-propagate nicely in the network, this is implemented with + the detach() trick + - Parameters scale and zero_point are recomputed every update_step + forward pass to reduce the overhead + - At test time, the weights are fully quantized + """ + + def __init__( + self, + in_channels, + out_channels, + kernel_size, + stride=1, + padding=0, + dilation=1, + groups=1, + bias=True, + padding_mode="zeros", + p=0, + bits=8, + method="histogram", + update_step=1000, + ): + kernel_size = _pair(kernel_size) + stride = _pair(stride) + padding = _pair(padding) + dilation = _pair(dilation) + super(IntConv2d, self).__init__( + in_channels, + out_channels, + kernel_size, + stride, + padding, + dilation, + False, + _pair(0), + groups, + bias, + padding_mode, + ) + + # quantization parameters + self.p = p + self.bits = bits + self.method = method + self.update_step = update_step + self.counter = 0 + + def _conv_forward(self, input, weight): + if self.padding_mode != "zeros": + return F.conv2d( + F.pad(input, self._padding_repeated_twice, mode=self.padding_mode), + weight, + self.bias, + self.stride, + _pair(0), + self.dilation, + self.groups, + ) + return F.conv2d( + input, + weight, + self.bias, + self.stride, + self.padding, + self.dilation, + self.groups, + ) + + def forward(self, input): + # train with QuantNoise and evaluate the fully quantized network + p = self.p if self.training else 1 + + # update parameters every 100 iterations + if self.counter % self.update_step == 0: + self.scale = None + self.zero_point = None + self.counter += 1 + + # quantize weight + weight_quantized, self.scale, self.zero_point = emulate_int( + self.weight.detach(), + bits=self.bits, + method=self.method, + scale=self.scale, + zero_point=self.zero_point, + ) + + # mask to apply noise + mask = torch.zeros_like(self.weight) + mask.bernoulli_(1 - p) + noise = (weight_quantized - self.weight).masked_fill(mask.bool(), 0) + + # using straight-through estimator (STE) + clamp_low = -self.scale * self.zero_point + clamp_high = self.scale * (2**self.bits - 1 - self.zero_point) + weight = ( + torch.clamp(self.weight, clamp_low.item(), clamp_high.item()) + + noise.detach() + ) + + # return output + output = self._conv_forward(input, weight) + return output + + def extra_repr(self): + return ( + "in_channels={}, out_channels={}, kernel_size={}, stride={}, " + "padding={}, dilation={}, groups={}, bias={}, quant_noise={}, " + "bits={}, method={}".format( + self.in_channels, + self.out_channels, + self.kernel_size, + self.stride, + self.padding, + self.dilation, + self.groups, + self.bias is not None, + self.p, + self.bits, + self.method, + ) + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qemb.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qemb.py new file mode 100644 index 00000000..3b293ac3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qemb.py @@ -0,0 +1,147 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from ..ops import emulate_int + + +class IntEmbedding(nn.Module): + """ + Quantized counterpart of the nn.Embedding module that applies QuantNoise during training. + + Args: + - num_embeddings: number of tokens + - embedding_dim: embedding dimension + - p: amount of noise to inject (0 = no quantization, 1 = quantize all the weights) + - bits: number of bits + - method: choose among {"tensor", "histogram", "channel"} + - update_step: recompute scale and zero_point every update_steps iterations + + Remarks: + - We use the straight-through estimator so that the gradients + back-propagate nicely in the network, this is implemented with + the detach() trick + - Parameters scale and zero_point are recomputed every update_step + forward pass to reduce the overhead + - At test time, the weights are fully quantized + """ + + def __init__( + self, + num_embeddings, + embedding_dim, + padding_idx=None, + max_norm=None, + norm_type=2.0, + scale_grad_by_freq=False, + sparse=False, + _weight=None, + p=0, + update_step=1000, + bits=8, + method="histogram", + ): + super(IntEmbedding, self).__init__() + self.num_embeddings = num_embeddings + self.embedding_dim = embedding_dim + if padding_idx is not None: + if padding_idx > 0: + assert ( + padding_idx < self.num_embeddings + ), "Padding_idx must be within num_embeddings" + elif padding_idx < 0: + assert ( + padding_idx >= -self.num_embeddings + ), "Padding_idx must be within num_embeddings" + padding_idx = self.num_embeddings + padding_idx + self.padding_idx = padding_idx + self.max_norm = max_norm + self.norm_type = norm_type + self.scale_grad_by_freq = scale_grad_by_freq + if _weight is None: + self.weight = nn.Parameter(torch.Tensor(num_embeddings, embedding_dim)) + self.reset_parameters() + else: + assert list(_weight.shape) == [ + num_embeddings, + embedding_dim, + ], "Shape of weight does not match num_embeddings and embedding_dim" + self.weight = nn.Parameter(_weight) + self.sparse = sparse + + # quantization parameters + self.p = p + self.bits = bits + self.method = method + self.update_step = update_step + self.counter = 0 + + def reset_parameters(self): + nn.init.normal_(self.weight) + if self.padding_idx is not None: + with torch.no_grad(): + self.weight[self.padding_idx].fill_(0) + + def forward(self, input): + # train with QuantNoise and evaluate the fully quantized network + p = self.p if self.training else 1 + + # update parameters every 1000 iterations + if self.counter % self.update_step == 0: + self.scale = None + self.zero_point = None + self.counter += 1 + + # quantize weight + weight_quantized, self.scale, self.zero_point = emulate_int( + self.weight.detach(), + bits=self.bits, + method=self.method, + scale=self.scale, + zero_point=self.zero_point, + ) + + # mask to apply noise + mask = torch.zeros_like(self.weight) + mask.bernoulli_(1 - p) + noise = (weight_quantized - self.weight).masked_fill(mask.bool(), 0) + + # using straight-through estimator (STE) + clamp_low = -self.scale * self.zero_point + clamp_high = self.scale * (2**self.bits - 1 - self.zero_point) + weight = ( + torch.clamp(self.weight, clamp_low.item(), clamp_high.item()) + + noise.detach() + ) + + # return output + output = F.embedding( + input, + weight, + self.padding_idx, + self.max_norm, + self.norm_type, + self.scale_grad_by_freq, + self.sparse, + ) + return output + + def extra_repr(self): + s = "{num_embeddings}, {embedding_dim}" + if self.padding_idx is not None: + s += ", padding_idx={padding_idx}" + if self.max_norm is not None: + s += ", max_norm={max_norm}" + if self.norm_type != 2: + s += ", norm_type={norm_type}" + if self.scale_grad_by_freq is not False: + s += ", scale_grad_by_freq={scale_grad_by_freq}" + if self.sparse is not False: + s += ", sparse=True" + s += "quant_noise={p}, bits={bits}, method={method}" + return s.format(**self.__dict__) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qlinear.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qlinear.py new file mode 100644 index 00000000..78606a25 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/modules/qlinear.py @@ -0,0 +1,113 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.nn as nn +import torch.nn.functional as F + +from ..ops import emulate_int + + +class IntLinear(nn.Module): + """ + Quantized counterpart of the nn.Linear module that applies QuantNoise during training. + + Args: + - in_features: input features + - out_features: output features + - bias: bias or not + - p: amount of noise to inject (0 = no quantization, 1 = quantize all the weights) + - bits: number of bits + - method: choose among {"tensor", "histogram", "channel"} + - update_step: recompute scale and zero_point every update_steps iterations + + Remarks: + - We use the straight-through estimator so that the gradients + back-propagate nicely in the network, this is implemented with + the detach() trick. + - Parameters scale and zero_point are recomputed every update_step + forward pass to reduce the overhead + - At test time, the weights are fully quantized + """ + + def __init__( + self, + in_features, + out_features, + bias=True, + p=0, + update_step=3000, + bits=8, + method="histogram", + ): + super(IntLinear, self).__init__() + self.in_features = int(in_features) + self.out_features = int(out_features) + self.weight = torch.nn.Parameter(torch.Tensor(out_features, in_features)) + self.chosen_bias = bias + if self.chosen_bias: + self.bias = torch.nn.Parameter(torch.Tensor(out_features)) + else: + self.register_parameter("bias", None) + self.reset_parameters() + + # quantization parameters + self.p = p + self.bits = bits + self.method = method + self.update_step = update_step + self.counter = 0 + + def reset_parameters(self): + nn.init.xavier_uniform_(self.weight) + if self.chosen_bias: + nn.init.constant_(self.bias, 0.0) + return + + def forward(self, input): + # train with QuantNoise and evaluate the fully quantized network + p = self.p if self.training else 1 + + # update parameters every 100 iterations + if self.counter % self.update_step == 0: + self.scale = None + self.zero_point = None + self.counter += 1 + + # quantize weight + weight_quantized, self.scale, self.zero_point = emulate_int( + self.weight.detach(), + bits=self.bits, + method=self.method, + scale=self.scale, + zero_point=self.zero_point, + ) + + # mask to apply noise + mask = torch.zeros_like(self.weight) + mask.bernoulli_(1 - p) + noise = (weight_quantized - self.weight).masked_fill(mask.bool(), 0) + + # using straight-through estimator (STE) + clamp_low = -self.scale * self.zero_point + clamp_high = self.scale * (2**self.bits - 1 - self.zero_point) + weight = ( + torch.clamp(self.weight, clamp_low.item(), clamp_high.item()) + + noise.detach() + ) + + # return output + output = F.linear(input, weight, self.bias) + return output + + def extra_repr(self): + return "in_features={}, out_features={}, bias={}, quant_noise={}, bits={}, method={}".format( + self.in_features, + self.out_features, + self.bias is not None, + self.p, + self.bits, + self.method, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/ops.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/ops.py new file mode 100644 index 00000000..e0f9a0c1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/ops.py @@ -0,0 +1,59 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch + +try: + import torch.ao.quantization as quantization +except ImportError: + import torch.quantization as quantization + + +def emulate_int(w, bits, method, scale=None, zero_point=None): + q = globals()[f"emulate_int8_{method}"] + return q(w, scale=scale, zero_point=zero_point, bits=bits) + + +def quantize(w, scale, zero_point, bits=8): + # In the default behavior, max_val = 255. + max_val = 2**bits - 1 + return ( + torch.clamp(torch.round(w / scale + zero_point), 0, max_val) - zero_point + ) * scale + + +def emulate_int8_histogram(w, scale=None, zero_point=None, bits=8): + if scale is None: + obs = quantization.observer.HistogramObserver() + obs.to(device=w.device) + _ = obs(w.float()) + scale, zero_point = obs.calculate_qparams() + scale = scale.cuda().type_as(w) + zero_point = zero_point.cuda().type_as(w) + return quantize(w, scale, zero_point, bits=bits), scale, zero_point + + +def emulate_int8_channel(w, scale=None, zero_point=None, bits=8): + if scale is None: + obs = quantization.observer.PerChannelMinMaxObserver( + ch_axis=-1, qscheme=torch.per_channel_symmetric + ) + obs.to(device=w.device) + _ = obs(w) + scale, zero_point, ch_axis = obs.get_qparams() + scale = scale.cuda().type_as(w) + zero_point = zero_point.cuda().type_as(w) + return quantize(w, scale, zero_point, bits=bits), scale, zero_point + + +def emulate_int8_tensor(w, scale=None, zero_point=None, bits=8): + if scale is None: + obs = quantization.observer.MinMaxObserver() + obs.to(device=w.device) + _ = obs(w) + scale, zero_point = obs.calculate_qparams() + scale = scale.cuda().type_as(w) + zero_point = zero_point.cuda().type_as(w) + return quantize(w, scale, zero_point, bits=bits), scale, zero_point diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/utils.py b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/utils.py new file mode 100644 index 00000000..d4b1cc25 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/quantization/scalar/utils.py @@ -0,0 +1,80 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from operator import attrgetter + +import torch.distributed as dist +import torch.nn as nn + +from ..pq.utils import attrsetter, get_layers +from .modules import ActivationQuantizer, IntConv2d, IntEmbedding, IntLinear + + +MAPPING = {nn.Linear: IntLinear, nn.Embedding: IntEmbedding, nn.Conv2d: IntConv2d} + + +def quantize_model_( + model, p=0.2, bits=8, update_step=3000, method="histogram", remove_weights=False +): + """ + Replaces all modules with their scalar quantized counterpart and + registers hooks to quantize the post-ativations of those modules. + + Args: + - model: a nn.Module + - p: amount of noise (0 for no noise, 1 to quantize all the weights/activations) + - bits: number of bits + - update_step: update quantization parameters every update_step steps + """ + # quantize all layers + # remove weights indicates whether the weights extension should be removed, in addition to + # weight_orig and weight extension on names + quantized_layers = get_layers(model, "(.*?)", remove_weights=remove_weights) + + for layer in quantized_layers: + + # book-keeping + is_master_process = (not dist.is_initialized()) or ( + dist.is_initialized() and dist.get_rank() == 0 + ) + + # recover module + module = attrgetter(layer)(model) + if is_master_process: + logging.info( + f"Quantizing layer {layer} with bits={bits} and QuantNoise={p}" + ) + + # quantization params + q_params = { + "p": p, + "update_step": update_step, + "bits": bits, + "method": method, + "counter": 0, + } + + # instantiate the quantized counterpart + if isinstance(module, tuple(MAPPING.keys())): + QuantizedModule = MAPPING[module.__class__] + quantized_module = QuantizedModule.__new__(QuantizedModule) + params = module.__dict__ + params.update(q_params) + quantized_module.__dict__.update(params) + + else: + if is_master_process: + logging.info(f"Module {module} not yet supported for quantization") + continue + + # activation quantization + a_q = ActivationQuantizer(quantized_module, p=0, bits=bits, method=method) + + # replace layer by its quantized counterpart + attrsetter(layer)(model, quantized_module) + + # return name of quantized layers + return quantized_layers diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/rotary_positional_embedding.py b/PyTorch/NLP/new-Transformer/fairseq/modules/rotary_positional_embedding.py new file mode 100644 index 00000000..84b88984 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/rotary_positional_embedding.py @@ -0,0 +1,51 @@ +import torch + + +class RotaryPositionalEmbedding(torch.nn.Module): + def __init__(self, dim, base=10000, precision=torch.half): + """Rotary positional embedding + Reference : https://blog.eleuther.ai/rotary-embeddings/ + Paper: https://arxiv.org/pdf/2104.09864.pdf + Args: + dim: Dimension of embedding + base: Base value for exponential + precision: precision to use for numerical values + """ + super().__init__() + inv_freq = 1.0 / (base ** (torch.arange(0, dim, 2).float() / dim)) + self.register_buffer("inv_freq", inv_freq) + self.seq_len_cached = None + self.cos_cached = None + self.sin_cached = None + self.precision = precision + + def forward(self, x, seq_len=None): + """ + Args: + x: Input x with T X B X C + seq_len: Sequence length of input x + """ + if seq_len != self.seq_len_cached: + self.seq_len_cached = seq_len + t = torch.arange(seq_len, device=x.device).type_as(self.inv_freq) + freqs = torch.einsum("i,j->ij", t, self.inv_freq) + emb = torch.cat((freqs, freqs), dim=-1).to(x.device) + self.cos_cached = emb.cos()[:, None, None, :] + self.sin_cached = emb.sin()[:, None, None, :] + return self.cos_cached, self.sin_cached + + +# rotary pos emb helpers: +def rotate_half(x): + x1, x2 = x[..., : x.shape[-1] // 2], x[..., x.shape[-1] // 2 :] + return torch.cat( + (-x2, x1), dim=x1.ndim - 1 + ) # dim=-1 triggers a bug in earlier torch versions + + +def apply_rotary_pos_emb(q, k, cos, sin, offset: int = 0): + cos, sin = ( + cos[offset : q.shape[0] + offset, ...], + sin[offset : q.shape[0] + offset, ...], + ) + return (q * cos) + (rotate_half(q) * sin), (k * cos) + (rotate_half(k) * sin) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/same_pad.py b/PyTorch/NLP/new-Transformer/fairseq/modules/same_pad.py new file mode 100644 index 00000000..4c04990e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/same_pad.py @@ -0,0 +1,21 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from torch import nn + + +class SamePad(nn.Module): + def __init__(self, kernel_size, causal=False): + super().__init__() + if causal: + self.remove = kernel_size - 1 + else: + self.remove = 1 if kernel_size % 2 == 0 else 0 + + def forward(self, x): + if self.remove > 0: + x = x[:, :, : -self.remove] + return x diff --git a/PyTorch/NLP/Transformer/fairseq/modules/scalar_bias.py b/PyTorch/NLP/new-Transformer/fairseq/modules/scalar_bias.py similarity index 71% rename from PyTorch/NLP/Transformer/fairseq/modules/scalar_bias.py rename to PyTorch/NLP/new-Transformer/fairseq/modules/scalar_bias.py index 969f3ac3..c96247c7 100644 --- a/PyTorch/NLP/Transformer/fairseq/modules/scalar_bias.py +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/scalar_bias.py @@ -1,9 +1,7 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. +# Copyright (c) Facebook, Inc. and its affiliates. # -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. # import torch diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/sinusoidal_positional_embedding.py b/PyTorch/NLP/new-Transformer/fairseq/modules/sinusoidal_positional_embedding.py new file mode 100644 index 00000000..4793ecfb --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/sinusoidal_positional_embedding.py @@ -0,0 +1,105 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from typing import Any, Optional + +import torch +import torch.onnx.operators +from fairseq import utils +from torch import Tensor, nn + + +class SinusoidalPositionalEmbedding(nn.Module): + """This module produces sinusoidal positional embeddings of any length. + + Padding symbols are ignored. + """ + + def __init__(self, embedding_dim, padding_idx, init_size=1024): + super().__init__() + self.embedding_dim = embedding_dim + self.padding_idx = padding_idx if padding_idx is not None else 0 + self.weights = SinusoidalPositionalEmbedding.get_embedding( + init_size, embedding_dim, padding_idx + ) + self.onnx_trace = False + self.register_buffer("_float_tensor", torch.FloatTensor(1)) + self.max_positions = int(1e5) + + def prepare_for_onnx_export_(self): + self.onnx_trace = True + + @staticmethod + def get_embedding( + num_embeddings: int, embedding_dim: int, padding_idx: Optional[int] = None + ): + """Build sinusoidal embeddings. + + This matches the implementation in tensor2tensor, but differs slightly + from the description in Section 3.5 of "Attention Is All You Need". + """ + half_dim = embedding_dim // 2 + emb = math.log(10000) / (half_dim - 1) + emb = torch.exp(torch.arange(half_dim, dtype=torch.float) * -emb) + emb = torch.arange(num_embeddings, dtype=torch.float).unsqueeze( + 1 + ) * emb.unsqueeze(0) + emb = torch.cat([torch.sin(emb), torch.cos(emb)], dim=1).view( + num_embeddings, -1 + ) + if embedding_dim % 2 == 1: + # zero pad + emb = torch.cat([emb, torch.zeros(num_embeddings, 1)], dim=1) + if padding_idx is not None: + emb[padding_idx, :] = 0 + return emb + + def forward( + self, + input, + incremental_state: Optional[Any] = None, + timestep: Optional[Tensor] = None, + positions: Optional[Any] = None, + ): + """Input is expected to be of size [bsz x seqlen].""" + bspair = torch.onnx.operators.shape_as_tensor(input) + bsz, seq_len = bspair[0], bspair[1] + max_pos = self.padding_idx + 1 + seq_len + if self.weights is None or max_pos > self.weights.size(0): + # recompute/expand embeddings if needed + self.weights = SinusoidalPositionalEmbedding.get_embedding( + max_pos, self.embedding_dim, self.padding_idx + ) + self.weights = self.weights.to(self._float_tensor) + + if incremental_state is not None: + # positions is the same for every token when decoding a single step + pos = timestep.view(-1)[0] + 1 if timestep is not None else seq_len + if self.onnx_trace: + return ( + self.weights.index_select(index=self.padding_idx + pos, dim=0) + .unsqueeze(1) + .repeat(bsz, 1, 1) + ) + return self.weights[self.padding_idx + pos, :].expand(bsz, 1, -1) + + positions = utils.make_positions( + input, self.padding_idx, onnx_trace=self.onnx_trace + ) + if self.onnx_trace: + flat_embeddings = self.weights.detach().index_select(0, positions.view(-1)) + embedding_shape = torch.cat( + (bsz.view(1), seq_len.view(1), torch.tensor([-1], dtype=torch.long)) + ) + embeddings = torch.onnx.operators.reshape_from_tensor_shape( + flat_embeddings, embedding_shape + ) + return embeddings + return ( + self.weights.index_select(0, positions.view(-1)) + .view(bsz, seq_len, -1) + .detach() + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_multihead_attention.py b/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_multihead_attention.py new file mode 100644 index 00000000..3cbd9d67 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_multihead_attention.py @@ -0,0 +1,140 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch + +from .multihead_attention import MultiheadAttention + + +class SparseMultiheadAttention(MultiheadAttention): + """Sparse Multi-Headed Attention. + + "Generating Long Sequences with Sparse Transformers". Implements + fixed factorized self attention, where l=stride and c=expressivity. + A(1) includes all words in the stride window and A(2) takes a summary of c + words from the end of each stride window. + If is_bidirectional=False, we do not include any words past the current word, + as in the paper. + """ + + def __init__( + self, + embed_dim, + num_heads, + kdim=None, + vdim=None, + dropout=0.0, + bias=True, + add_bias_kv=False, + add_zero_attn=False, + self_attention=False, + encoder_decoder_attention=False, + stride=32, + expressivity=8, + is_bidirectional=True, + ): + + super().__init__( + embed_dim, + num_heads, + kdim, + vdim, + dropout, + bias, + add_bias_kv, + add_zero_attn, + self_attention, + encoder_decoder_attention, + ) + + self.is_bidirectional = is_bidirectional + self.stride = stride + self.expressivity = expressivity + assert self.stride > 0 and self.stride >= self.expressivity + + # Used for Ai(2) calculations - beginning of [l-c, l] range + def compute_checkpoint(self, word_index): + if word_index % self.stride == 0 and word_index != 0: + checkpoint_index = word_index - self.expressivity + else: + checkpoint_index = ( + math.floor(word_index / self.stride) * self.stride + + self.stride + - self.expressivity + ) + return checkpoint_index + + # Computes Ai(2) + def compute_subset_summaries(self, absolute_max): + checkpoint_index = self.compute_checkpoint(0) + subset_two = set() + while checkpoint_index <= absolute_max - 1: + summary = set( + range( + checkpoint_index, + min(checkpoint_index + self.expressivity + 1, absolute_max), + ) + ) + subset_two = subset_two.union(summary) + checkpoint_index = self.compute_checkpoint(checkpoint_index + self.stride) + return subset_two + + # Sparse Transformer Fixed Attention Pattern: https://arxiv.org/pdf/1904.10509.pdf + def compute_fixed_attention_subset(self, word_index, tgt_len): + # +1s account for range function; [min, max) -> [min, max] + if not self.is_bidirectional: + absolute_max = word_index + 1 + else: + absolute_max = tgt_len + + # Subset 1 - whole window + rounded_index = ( + math.floor((word_index + self.stride) / self.stride) * self.stride + ) + if word_index % self.stride == 0 and word_index != 0: + subset_one = set( + range(word_index - self.stride, min(absolute_max, word_index + 1)) + ) + else: + subset_one = set( + range( + max(0, rounded_index - self.stride), + min(absolute_max, rounded_index + 1), + ) + ) + + # Subset 2 - summary per window + # If bidirectional, subset 2 is the same for every index + subset_two = set() + if not self.is_bidirectional: + subset_two = self.compute_subset_summaries(absolute_max) + + return subset_one.union(subset_two) + + # Compute sparse mask - if bidirectional, can pre-compute and store + def buffered_sparse_mask(self, tensor, tgt_len, src_len): + assert tgt_len > self.stride + sparse_mask = torch.empty((tgt_len, src_len)).float().fill_(float("-inf")) + + # If bidirectional, subset 2 is the same for every index + subset_summaries = set() + if self.is_bidirectional: + subset_summaries = self.compute_subset_summaries(tgt_len) + + for i in range(tgt_len): + fixed_attention_subset = self.compute_fixed_attention_subset(i, tgt_len) + fixed_attention_subset = fixed_attention_subset.union(subset_summaries) + included_word_indices = torch.LongTensor(list(fixed_attention_subset)) + sparse_mask[i].index_fill_(0, included_word_indices, 0) + return sparse_mask.type_as(tensor) + + def apply_sparse_mask(self, attn_weights, tgt_len, src_len, bsz): + sparse_mask = self.buffered_sparse_mask(attn_weights, tgt_len, src_len) + sparse_mask = sparse_mask.unsqueeze(0).expand( + bsz * self.num_heads, tgt_len, src_len + ) + attn_weights += sparse_mask diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_transformer_sentence_encoder.py b/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_transformer_sentence_encoder.py new file mode 100644 index 00000000..f41ec093 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_transformer_sentence_encoder.py @@ -0,0 +1,96 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn as nn +from fairseq.modules import TransformerSentenceEncoder +from fairseq.modules.sparse_transformer_sentence_encoder_layer import ( + SparseTransformerSentenceEncoderLayer, +) + + +class SparseTransformerSentenceEncoder(TransformerSentenceEncoder): + """ + Sparse implementation of the TransformerSentenceEncoder + - see SparseMultiheadAttention + """ + + def __init__( + self, + padding_idx: int, + vocab_size: int, + num_encoder_layers: int = 6, + embedding_dim: int = 768, + ffn_embedding_dim: int = 3072, + num_attention_heads: int = 8, + dropout: float = 0.1, + attention_dropout: float = 0.1, + activation_dropout: float = 0.1, + max_seq_len: int = 256, + num_segments: int = 2, + use_position_embeddings: bool = True, + offset_positions_by_padding: bool = True, + encoder_normalize_before: bool = False, + apply_bert_init: bool = False, + activation_fn: str = "relu", + learned_pos_embedding: bool = True, + embed_scale: float = None, + freeze_embeddings: bool = False, + n_trans_layers_to_freeze: int = 0, + export: bool = False, + is_bidirectional: bool = True, + stride: int = 32, + expressivity: int = 8, + ) -> None: + + super().__init__( + padding_idx, + vocab_size, + num_encoder_layers, + embedding_dim, + ffn_embedding_dim, + num_attention_heads, + dropout, + attention_dropout, + activation_dropout, + max_seq_len, + num_segments, + use_position_embeddings, + offset_positions_by_padding, + encoder_normalize_before, + apply_bert_init, + activation_fn, + learned_pos_embedding, + embed_scale, + freeze_embeddings, + n_trans_layers_to_freeze, + export, + ) + + self.layers = nn.ModuleList( + [ + SparseTransformerSentenceEncoderLayer( + embedding_dim=self.embedding_dim, + ffn_embedding_dim=ffn_embedding_dim, + num_attention_heads=num_attention_heads, + dropout=dropout, + attention_dropout=attention_dropout, + activation_dropout=activation_dropout, + activation_fn=activation_fn, + export=export, + is_bidirectional=is_bidirectional, + stride=stride, + expressivity=expressivity, + ) + for _ in range(num_encoder_layers) + ] + ) + + def freeze_module_params(m): + if m is not None: + for p in m.parameters(): + p.requires_grad = False + + for layer in range(n_trans_layers_to_freeze): + freeze_module_params(self.layers[layer]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_transformer_sentence_encoder_layer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_transformer_sentence_encoder_layer.py new file mode 100644 index 00000000..d95da59c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/sparse_transformer_sentence_encoder_layer.py @@ -0,0 +1,51 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.modules import TransformerSentenceEncoderLayer +from fairseq.modules.sparse_multihead_attention import SparseMultiheadAttention + + +class SparseTransformerSentenceEncoderLayer(TransformerSentenceEncoderLayer): + """ + Implements a Sprase Transformer Encoder Layer (see SparseMultiheadAttention) + """ + + def __init__( + self, + embedding_dim: int = 768, + ffn_embedding_dim: int = 3072, + num_attention_heads: int = 8, + dropout: float = 0.1, + attention_dropout: float = 0.1, + activation_dropout: float = 0.1, + activation_fn: str = "relu", + export: bool = False, + is_bidirectional: bool = True, + stride: int = 32, + expressivity: int = 8, + ) -> None: + + super().__init__( + embedding_dim, + ffn_embedding_dim, + num_attention_heads, + dropout, + attention_dropout, + activation_dropout, + activation_fn, + export, + ) + + self.self_attn = SparseMultiheadAttention( + self.embedding_dim, + num_attention_heads, + dropout=attention_dropout, + add_bias_kv=False, + add_zero_attn=False, + self_attention=True, + is_bidirectional=is_bidirectional, + stride=stride, + expressivity=expressivity, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_layer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_layer.py new file mode 100644 index 00000000..2e687b94 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_layer.py @@ -0,0 +1,563 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Dict, List, Optional + +import torch +import torch.nn as nn +from fairseq import utils +from fairseq.modules import LayerNorm, MultiheadAttention +from fairseq.modules.fairseq_dropout import FairseqDropout +from fairseq.modules.quant_noise import quant_noise +from torch import Tensor +from fairseq.models.transformer import ( + TransformerConfig, +) + + +class TransformerEncoderLayerBase(nn.Module): + """Encoder layer block. + + In the original paper each operation (multi-head attention or FFN) is + postprocessed with: `dropout -> add residual -> layernorm`. In the + tensor2tensor code they suggest that learning is more robust when + preprocessing each layer with layernorm and postprocessing with: + `dropout -> add residual`. We default to the approach in the paper, but the + tensor2tensor approach can be enabled by setting + *cfg.encoder.normalize_before* to ``True``. + + Args: + args (argparse.Namespace): parsed command-line arguments + """ + + def __init__(self, cfg, return_fc=False): + super().__init__() + self.cfg = cfg + self.return_fc = return_fc + self.embed_dim = cfg.encoder.embed_dim + self.quant_noise = cfg.quant_noise.pq + self.quant_noise_block_size = cfg.quant_noise.pq_block_size + self.self_attn = self.build_self_attention(self.embed_dim, cfg) + self.self_attn_layer_norm = LayerNorm(self.embed_dim, export=cfg.export) + self.dropout_module = FairseqDropout( + cfg.dropout, module_name=self.__class__.__name__ + ) + self.activation_fn = utils.get_activation_fn(activation=cfg.activation_fn) + activation_dropout_p = cfg.activation_dropout + if activation_dropout_p == 0: + # for backwards compatibility with models that use cfg.relu_dropout + activation_dropout_p = cfg.relu_dropout or 0 + self.activation_dropout_module = FairseqDropout( + float(activation_dropout_p), module_name=self.__class__.__name__ + ) + self.normalize_before = cfg.encoder.normalize_before + self.fc1 = self.build_fc1( + self.embed_dim, + cfg.encoder.ffn_embed_dim, + self.quant_noise, + self.quant_noise_block_size, + ) + self.fc2 = self.build_fc2( + cfg.encoder.ffn_embed_dim, + self.embed_dim, + self.quant_noise, + self.quant_noise_block_size, + ) + + self.final_layer_norm = LayerNorm(self.embed_dim, export=cfg.export) + + def build_fc1(self, input_dim, output_dim, q_noise, qn_block_size): + return quant_noise( + nn.Linear(input_dim, output_dim), p=q_noise, block_size=qn_block_size + ) + + def build_fc2(self, input_dim, output_dim, q_noise, qn_block_size): + return quant_noise( + nn.Linear(input_dim, output_dim), p=q_noise, block_size=qn_block_size + ) + + def _get_fc_rank(self, remove_num: int) -> List[int]: + f1_filter_param = [] + for i in range(self.fc1.out_features): + f1_filter_param.append( + torch.sum(torch.abs(self.fc1.weight[i])) + + torch.sum(torch.abs(self.fc2.weight[:, i])) + + torch.abs(self.fc1.bias[i]) + ) + return sorted( + range(len(f1_filter_param)), key=lambda k: f1_filter_param[k], reverse=False + )[0:remove_num] + + def _prune_fc_layer(self, remove_index: List[int]): + new_fc1_weight = [] + new_fc1_bias = [] + for i in range(self.fc1.out_features): + if i not in remove_index: + new_fc1_weight.append(self.fc1.weight[i]) + new_fc1_bias.append(self.fc1.bias[i]) + + new_fc1_weight = torch.stack(new_fc1_weight).detach() + new_fc1_weight.requires_grad = True + + new_fc1_bias = torch.stack(new_fc1_bias).detach() + new_fc1_bias.requires_grad = True + + self.fc1 = quant_noise( + nn.Linear(self.fc1.in_features, self.fc1.out_features - len(remove_index)), + p=self.quant_noise, + block_size=self.quant_noise_block_size, + ) + self.fc1.weight = torch.nn.Parameter(new_fc1_weight) + self.fc1.bias = torch.nn.Parameter(new_fc1_bias) + + new_fc2_weight = [] + new_fc2_bias = [] + for i in range(self.fc2.in_features): + if i not in remove_index: + new_fc2_weight.append(self.fc2.weight[:, i]) + new_fc2_bias = self.fc2.bias.detach() + + new_fc2_weight = torch.stack(new_fc2_weight, dim=-1).detach() + new_fc2_weight.requires_grad = True + + new_fc2_bias = self.fc2.bias.detach() + new_fc2_bias.requires_grad = True + + self.fc2 = quant_noise( + nn.Linear(self.fc2.in_features - len(remove_index), self.fc2.out_features), + p=self.quant_noise, + block_size=self.quant_noise_block_size, + ) + self.fc2.weight = torch.nn.Parameter(new_fc2_weight) + self.fc2.bias = torch.nn.Parameter(new_fc2_bias) + + def build_self_attention(self, embed_dim, cfg): + return MultiheadAttention( + embed_dim, + cfg.encoder.attention_heads, + dropout=cfg.attention_dropout, + self_attention=True, + q_noise=self.quant_noise, + qn_block_size=self.quant_noise_block_size, + xformers_att_config=cfg.encoder.xformers_att_config, + ) + + def residual_connection(self, x, residual): + return residual + x + + def upgrade_state_dict_named(self, state_dict, name): + """ + Rename layer norm states from `...layer_norms.0.weight` to + `...self_attn_layer_norm.weight` and `...layer_norms.1.weight` to + `...final_layer_norm.weight` + """ + layer_norm_map = {"0": "self_attn_layer_norm", "1": "final_layer_norm"} + for old, new in layer_norm_map.items(): + for m in ("weight", "bias"): + k = "{}.layer_norms.{}.{}".format(name, old, m) + if k in state_dict: + state_dict["{}.{}.{}".format(name, new, m)] = state_dict[k] + del state_dict[k] + + def forward( + self, + x, + encoder_padding_mask: Optional[Tensor], + attn_mask: Optional[Tensor] = None, + ): + """ + Args: + x (Tensor): input to the layer of shape `(seq_len, batch, embed_dim)` + encoder_padding_mask (ByteTensor): binary ByteTensor of shape + `(batch, seq_len)` where padding elements are indicated by ``1``. + attn_mask (ByteTensor): binary tensor of shape `(tgt_len, src_len)`, + where `tgt_len` is the length of output and `src_len` is the + length of input, though here both are equal to `seq_len`. + `attn_mask[tgt_i, src_j] = 1` means that when calculating the + embedding for `tgt_i`, we exclude (mask out) `src_j`. This is + useful for strided self-attention. + + Returns: + encoded output of shape `(seq_len, batch, embed_dim)` + """ + # anything in original attn_mask = 1, becomes -1e8 + # anything in original attn_mask = 0, becomes 0 + # Note that we cannot use -inf here, because at some edge cases, + # the attention weight (before softmax) for some padded element in query + # will become -inf, which results in NaN in model parameters + if attn_mask is not None: + attn_mask = attn_mask.masked_fill( + attn_mask.to(torch.bool), -1e8 if x.dtype == torch.float32 else -1e4 + ) + + residual = x + if self.normalize_before: + x = self.self_attn_layer_norm(x) + x, _ = self.self_attn( + query=x, + key=x, + value=x, + key_padding_mask=encoder_padding_mask, + need_weights=False, + attn_mask=attn_mask, + ) + x = self.dropout_module(x) + x = self.residual_connection(x, residual) + if not self.normalize_before: + x = self.self_attn_layer_norm(x) + + residual = x + if self.normalize_before: + x = self.final_layer_norm(x) + x = self.activation_fn(self.fc1(x)) + x = self.activation_dropout_module(x) + x = self.fc2(x) + + fc_result = x + + x = self.dropout_module(x) + x = self.residual_connection(x, residual) + if not self.normalize_before: + x = self.final_layer_norm(x) + + if self.return_fc and not torch.jit.is_scripting(): + return x, fc_result + return x + + +# backward compatible with the legacy argparse format +class TransformerEncoderLayer(TransformerEncoderLayerBase): + def __init__(self, args): + super().__init__(TransformerConfig.from_namespace(args)) + self.args = args + + def build_self_attention(self, embed_dim, args): + return super().build_self_attention( + embed_dim, TransformerConfig.from_namespace(args) + ) + + +class TransformerDecoderLayerBase(nn.Module): + """Decoder layer block. + + In the original paper each operation (multi-head attention, encoder + attention or FFN) is postprocessed with: `dropout -> add residual -> + layernorm`. In the tensor2tensor code they suggest that learning is more + robust when preprocessing each layer with layernorm and postprocessing with: + `dropout -> add residual`. We default to the approach in the paper, but the + tensor2tensor approach can be enabled by setting + *cfg.decoder.normalize_before* to ``True``. + + Args: + args (argparse.Namespace): parsed command-line arguments + no_encoder_attn (bool, optional): whether to attend to encoder outputs + (default: False). + """ + + def __init__( + self, cfg, no_encoder_attn=False, add_bias_kv=False, add_zero_attn=False + ): + super().__init__() + self.embed_dim = cfg.decoder.embed_dim + self.dropout_module = FairseqDropout( + cfg.dropout, module_name=self.__class__.__name__ + ) + self.quant_noise = cfg.quant_noise.pq + self.quant_noise_block_size = cfg.quant_noise.pq_block_size + + self.cross_self_attention = cfg.cross_self_attention + + self.self_attn = self.build_self_attention( + self.embed_dim, + cfg, + add_bias_kv=add_bias_kv, + add_zero_attn=add_zero_attn, + ) + self.attn_ln = ( + LayerNorm(self.embed_dim) + if utils.safe_getattr(cfg, "scale_attn", False) + else None + ) + self.nh = self.self_attn.num_heads + self.head_dim = self.self_attn.head_dim + scale_heads = utils.safe_getattr(cfg, "scale_heads", False) + self.c_attn = ( + nn.Parameter(torch.ones((self.nh,)), requires_grad=True) + if scale_heads + else None + ) + + self.activation_fn = utils.get_activation_fn(activation=cfg.activation_fn) + activation_dropout_p = cfg.activation_dropout + if activation_dropout_p == 0: + # for backwards compatibility with models that use cfg.relu_dropout + activation_dropout_p = cfg.relu_dropout or 0 + self.activation_dropout_module = FairseqDropout( + float(activation_dropout_p), module_name=self.__class__.__name__ + ) + self.normalize_before = cfg.decoder.normalize_before + + self.self_attn_layer_norm = LayerNorm(self.embed_dim, export=cfg.export) + + if no_encoder_attn: + self.encoder_attn = None + self.encoder_attn_layer_norm = None + else: + self.encoder_attn = self.build_encoder_attention(self.embed_dim, cfg) + self.encoder_attn_layer_norm = LayerNorm(self.embed_dim, export=cfg.export) + + self.ffn_layernorm = ( + LayerNorm(cfg.decoder.ffn_embed_dim) + if utils.safe_getattr(cfg, "scale_fc", False) + else None + ) + self.w_resid = ( + nn.Parameter( + torch.ones( + self.embed_dim, + ), + requires_grad=True, + ) + if utils.safe_getattr(cfg, "scale_resids", False) + else None + ) + + self.fc1 = self.build_fc1( + self.embed_dim, + cfg.decoder.ffn_embed_dim, + self.quant_noise, + self.quant_noise_block_size, + ) + self.fc2 = self.build_fc2( + cfg.decoder.ffn_embed_dim, + self.embed_dim, + self.quant_noise, + self.quant_noise_block_size, + ) + + self.final_layer_norm = LayerNorm(self.embed_dim, export=cfg.export) + self.need_attn = True + + self.onnx_trace = False + + def build_fc1(self, input_dim, output_dim, q_noise, qn_block_size): + return quant_noise(nn.Linear(input_dim, output_dim), q_noise, qn_block_size) + + def build_fc2(self, input_dim, output_dim, q_noise, qn_block_size): + return quant_noise(nn.Linear(input_dim, output_dim), q_noise, qn_block_size) + + def build_self_attention( + self, embed_dim, cfg, add_bias_kv=False, add_zero_attn=False + ): + return MultiheadAttention( + embed_dim, + cfg.decoder.attention_heads, + dropout=cfg.attention_dropout, + add_bias_kv=add_bias_kv, + add_zero_attn=add_zero_attn, + self_attention=not cfg.cross_self_attention, + q_noise=self.quant_noise, + qn_block_size=self.quant_noise_block_size, + xformers_att_config=cfg.decoder.xformers_att_config, + ) + + def build_encoder_attention(self, embed_dim, cfg): + return MultiheadAttention( + embed_dim, + cfg.decoder.attention_heads, + kdim=cfg.encoder.embed_dim, + vdim=cfg.encoder.embed_dim, + dropout=cfg.attention_dropout, + encoder_decoder_attention=True, + q_noise=self.quant_noise, + qn_block_size=self.quant_noise_block_size, + xformers_att_config=cfg.encoder.xformers_att_config, + ) + + def prepare_for_onnx_export_(self): + self.onnx_trace = True + + def residual_connection(self, x, residual): + return residual + x + + def forward( + self, + x, + encoder_out: Optional[torch.Tensor] = None, + encoder_padding_mask: Optional[torch.Tensor] = None, + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]] = None, + prev_self_attn_state: Optional[List[torch.Tensor]] = None, + prev_attn_state: Optional[List[torch.Tensor]] = None, + self_attn_mask: Optional[torch.Tensor] = None, + self_attn_padding_mask: Optional[torch.Tensor] = None, + need_attn: bool = False, + need_head_weights: bool = False, + ): + """ + Args: + x (Tensor): input to the layer of shape `(seq_len, batch, embed_dim)` + encoder_padding_mask (ByteTensor, optional): binary + ByteTensor of shape `(batch, src_len)` where padding + elements are indicated by ``1``. + need_attn (bool, optional): return attention weights + need_head_weights (bool, optional): return attention weights + for each head (default: return average over heads). + + Returns: + encoded output of shape `(seq_len, batch, embed_dim)` + """ + if need_head_weights: + need_attn = True + + residual = x + if self.normalize_before: + x = self.self_attn_layer_norm(x) + if prev_self_attn_state is not None: + prev_key, prev_value = prev_self_attn_state[:2] + saved_state: Dict[str, Optional[Tensor]] = { + "prev_key": prev_key, + "prev_value": prev_value, + } + if len(prev_self_attn_state) >= 3: + saved_state["prev_key_padding_mask"] = prev_self_attn_state[2] + assert incremental_state is not None + self.self_attn._set_input_buffer(incremental_state, saved_state) + _self_attn_input_buffer = self.self_attn._get_input_buffer(incremental_state) + if self.cross_self_attention and not ( + incremental_state is not None + and _self_attn_input_buffer is not None + and "prev_key" in _self_attn_input_buffer + ): + if self_attn_mask is not None: + assert encoder_out is not None + self_attn_mask = torch.cat( + (x.new_zeros(x.size(0), encoder_out.size(0)), self_attn_mask), dim=1 + ) + if self_attn_padding_mask is not None: + if encoder_padding_mask is None: + assert encoder_out is not None + encoder_padding_mask = self_attn_padding_mask.new_zeros( + encoder_out.size(1), encoder_out.size(0) + ) + self_attn_padding_mask = torch.cat( + (encoder_padding_mask, self_attn_padding_mask), dim=1 + ) + assert encoder_out is not None + y = torch.cat((encoder_out, x), dim=0) + else: + y = x + + x, attn = self.self_attn( + query=x, + key=y, + value=y, + key_padding_mask=self_attn_padding_mask, + incremental_state=incremental_state, + need_weights=False, + attn_mask=self_attn_mask, + ) + if self.c_attn is not None: + tgt_len, bsz = x.size(0), x.size(1) + x = x.view(tgt_len, bsz, self.nh, self.head_dim) + x = torch.einsum("tbhd,h->tbhd", x, self.c_attn) + x = x.reshape(tgt_len, bsz, self.embed_dim) + if self.attn_ln is not None: + x = self.attn_ln(x) + x = self.dropout_module(x) + x = self.residual_connection(x, residual) + if not self.normalize_before: + x = self.self_attn_layer_norm(x) + + if self.encoder_attn is not None and encoder_out is not None: + residual = x + if self.normalize_before: + x = self.encoder_attn_layer_norm(x) + if prev_attn_state is not None: + prev_key, prev_value = prev_attn_state[:2] + saved_state: Dict[str, Optional[Tensor]] = { + "prev_key": prev_key, + "prev_value": prev_value, + } + if len(prev_attn_state) >= 3: + saved_state["prev_key_padding_mask"] = prev_attn_state[2] + assert incremental_state is not None + self.encoder_attn._set_input_buffer(incremental_state, saved_state) + + x, attn = self.encoder_attn( + query=x, + key=encoder_out, + value=encoder_out, + key_padding_mask=encoder_padding_mask, + incremental_state=incremental_state, + static_kv=True, + need_weights=need_attn or (not self.training and self.need_attn), + need_head_weights=need_head_weights, + ) + x = self.dropout_module(x) + x = self.residual_connection(x, residual) + if not self.normalize_before: + x = self.encoder_attn_layer_norm(x) + + residual = x + if self.normalize_before: + x = self.final_layer_norm(x) + + x = self.activation_fn(self.fc1(x)) + x = self.activation_dropout_module(x) + if self.ffn_layernorm is not None: + x = self.ffn_layernorm(x) + x = self.fc2(x) + x = self.dropout_module(x) + if self.w_resid is not None: + residual = torch.mul(self.w_resid, residual) + x = self.residual_connection(x, residual) + if not self.normalize_before: + x = self.final_layer_norm(x) + if self.onnx_trace and incremental_state is not None: + saved_state = self.self_attn._get_input_buffer(incremental_state) + assert saved_state is not None + if self_attn_padding_mask is not None: + self_attn_state = [ + saved_state["prev_key"], + saved_state["prev_value"], + saved_state["prev_key_padding_mask"], + ] + else: + self_attn_state = [saved_state["prev_key"], saved_state["prev_value"]] + return x, attn, self_attn_state + return x, attn, None + + def make_generation_fast_(self, need_attn: bool = False, **kwargs): + self.need_attn = need_attn + + +# backward compatible with the legacy argparse format +class TransformerDecoderLayer(TransformerDecoderLayerBase): + def __init__( + self, args, no_encoder_attn=False, add_bias_kv=False, add_zero_attn=False + ): + super().__init__( + TransformerConfig.from_namespace(args), + no_encoder_attn=no_encoder_attn, + add_bias_kv=add_bias_kv, + add_zero_attn=add_zero_attn, + ) + self.args = args + + def build_self_attention( + self, embed_dim, args, add_bias_kv=False, add_zero_attn=False + ): + return super().build_self_attention( + embed_dim, + TransformerConfig.from_namespace(args), + add_bias_kv=add_bias_kv, + add_zero_attn=add_zero_attn, + ) + + def build_encoder_attention(self, embed_dim, args): + return super().build_encoder_attention( + embed_dim, + TransformerConfig.from_namespace(args), + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_sentence_encoder.py b/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_sentence_encoder.py new file mode 100644 index 00000000..5d2db91a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_sentence_encoder.py @@ -0,0 +1,291 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Optional, Tuple + +import torch +import torch.nn as nn +from fairseq.modules import ( + FairseqDropout, + LayerDropModuleList, + LayerNorm, + MultiheadAttention, + PositionalEmbedding, + TransformerSentenceEncoderLayer, +) +from fairseq.modules.quant_noise import quant_noise as apply_quant_noise_ + + +def init_bert_params(module): + """ + Initialize the weights specific to the BERT Model. + This overrides the default initializations depending on the specified arguments. + 1. If normal_init_linear_weights is set then weights of linear + layer will be initialized using the normal distribution and + bais will be set to the specified value. + 2. If normal_init_embed_weights is set then weights of embedding + layer will be initialized using the normal distribution. + 3. If normal_init_proj_weights is set then weights of + in_project_weight for MultiHeadAttention initialized using + the normal distribution (to be validated). + """ + + def normal_(data): + # with FSDP, module params will be on CUDA, so we cast them back to CPU + # so that the RNG is consistent with and without FSDP + data.copy_(data.cpu().normal_(mean=0.0, std=0.02).to(data.device)) + + if isinstance(module, nn.Linear): + normal_(module.weight.data) + if module.bias is not None: + module.bias.data.zero_() + if isinstance(module, nn.Embedding): + normal_(module.weight.data) + if module.padding_idx is not None: + module.weight.data[module.padding_idx].zero_() + if isinstance(module, MultiheadAttention): + normal_(module.q_proj.weight.data) + normal_(module.k_proj.weight.data) + normal_(module.v_proj.weight.data) + + +class TransformerSentenceEncoder(nn.Module): + """ + Implementation for a Bi-directional Transformer based Sentence Encoder used + in BERT/XLM style pre-trained models. + + This first computes the token embedding using the token embedding matrix, + position embeddings (if specified) and segment embeddings + (if specified). After applying the specified number of + TransformerEncoderLayers, it outputs all the internal states of the + encoder as well as the final representation associated with the first + token (usually CLS token). + + Input: + - tokens: B x T matrix representing sentences + - segment_labels: B x T matrix representing segment label for tokens + + Output: + - a tuple of the following: + - a list of internal model states used to compute the + predictions where each tensor has shape T x B x C + - sentence representation associated with first input token + in format B x C. + """ + + def __init__( + self, + padding_idx: int, + vocab_size: int, + num_encoder_layers: int = 6, + embedding_dim: int = 768, + ffn_embedding_dim: int = 3072, + num_attention_heads: int = 8, + dropout: float = 0.1, + attention_dropout: float = 0.1, + activation_dropout: float = 0.1, + layerdrop: float = 0.0, + max_seq_len: int = 256, + num_segments: int = 2, + use_position_embeddings: bool = True, + offset_positions_by_padding: bool = True, + encoder_normalize_before: bool = False, + apply_bert_init: bool = False, + activation_fn: str = "relu", + learned_pos_embedding: bool = True, + embed_scale: float = None, + freeze_embeddings: bool = False, + n_trans_layers_to_freeze: int = 0, + export: bool = False, + traceable: bool = False, + q_noise: float = 0.0, + qn_block_size: int = 8, + ) -> None: + + super().__init__() + self.padding_idx = padding_idx + self.vocab_size = vocab_size + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + self.layerdrop = layerdrop + self.max_seq_len = max_seq_len + self.embedding_dim = embedding_dim + self.num_segments = num_segments + self.use_position_embeddings = use_position_embeddings + self.apply_bert_init = apply_bert_init + self.learned_pos_embedding = learned_pos_embedding + self.traceable = traceable + + self.embed_tokens = self.build_embedding( + self.vocab_size, self.embedding_dim, self.padding_idx + ) + self.embed_scale = embed_scale + + if q_noise > 0: + self.quant_noise = apply_quant_noise_( + nn.Linear(self.embedding_dim, self.embedding_dim, bias=False), + q_noise, + qn_block_size, + ) + else: + self.quant_noise = None + + self.segment_embeddings = ( + nn.Embedding(self.num_segments, self.embedding_dim, padding_idx=None) + if self.num_segments > 0 + else None + ) + + self.embed_positions = ( + PositionalEmbedding( + self.max_seq_len, + self.embedding_dim, + padding_idx=(self.padding_idx if offset_positions_by_padding else None), + learned=self.learned_pos_embedding, + ) + if self.use_position_embeddings + else None + ) + + if encoder_normalize_before: + self.emb_layer_norm = LayerNorm(self.embedding_dim, export=export) + else: + self.emb_layer_norm = None + + if self.layerdrop > 0.0: + self.layers = LayerDropModuleList(p=self.layerdrop) + else: + self.layers = nn.ModuleList([]) + self.layers.extend( + [ + self.build_transformer_sentence_encoder_layer( + embedding_dim=self.embedding_dim, + ffn_embedding_dim=ffn_embedding_dim, + num_attention_heads=num_attention_heads, + dropout=self.dropout_module.p, + attention_dropout=attention_dropout, + activation_dropout=activation_dropout, + activation_fn=activation_fn, + export=export, + q_noise=q_noise, + qn_block_size=qn_block_size, + ) + for _ in range(num_encoder_layers) + ] + ) + + # Apply initialization of model params after building the model + if self.apply_bert_init: + self.apply(init_bert_params) + + def freeze_module_params(m): + if m is not None: + for p in m.parameters(): + p.requires_grad = False + + if freeze_embeddings: + freeze_module_params(self.embed_tokens) + freeze_module_params(self.segment_embeddings) + freeze_module_params(self.embed_positions) + freeze_module_params(self.emb_layer_norm) + + for layer in range(n_trans_layers_to_freeze): + freeze_module_params(self.layers[layer]) + + def build_embedding(self, vocab_size, embedding_dim, padding_idx): + return nn.Embedding(vocab_size, embedding_dim, padding_idx) + + def build_transformer_sentence_encoder_layer( + self, + embedding_dim, + ffn_embedding_dim, + num_attention_heads, + dropout, + attention_dropout, + activation_dropout, + activation_fn, + export, + q_noise, + qn_block_size, + ): + return TransformerSentenceEncoderLayer( + embedding_dim=embedding_dim, + ffn_embedding_dim=ffn_embedding_dim, + num_attention_heads=num_attention_heads, + dropout=dropout, + attention_dropout=attention_dropout, + activation_dropout=activation_dropout, + activation_fn=activation_fn, + export=export, + q_noise=q_noise, + qn_block_size=qn_block_size, + ) + + def forward( + self, + tokens: torch.Tensor, + segment_labels: torch.Tensor = None, + last_state_only: bool = False, + positions: Optional[torch.Tensor] = None, + token_embeddings: Optional[torch.Tensor] = None, + attn_mask: Optional[torch.Tensor] = None, + ) -> Tuple[torch.Tensor, torch.Tensor]: + is_tpu = tokens.device.type == "xla" + + # compute padding mask. This is needed for multi-head attention + padding_mask = tokens.eq(self.padding_idx) + if not self.traceable and not is_tpu and not padding_mask.any(): + padding_mask = None + + if token_embeddings is not None: + x = token_embeddings + else: + x = self.embed_tokens(tokens) + + if self.embed_scale is not None: + x = x * self.embed_scale + + if self.embed_positions is not None: + x = x + self.embed_positions(tokens, positions=positions) + + if self.segment_embeddings is not None and segment_labels is not None: + x = x + self.segment_embeddings(segment_labels) + + if self.quant_noise is not None: + x = self.quant_noise(x) + + if self.emb_layer_norm is not None: + x = self.emb_layer_norm(x) + + x = self.dropout_module(x) + + # account for padding while computing the representation + if padding_mask is not None: + x = x * (1 - padding_mask.unsqueeze(-1).type_as(x)) + + # B x T x C -> T x B x C + x = x.transpose(0, 1) + + inner_states = [] + if not last_state_only: + inner_states.append(x) + + for layer in self.layers: + x, _ = layer( + x, self_attn_padding_mask=padding_mask, self_attn_mask=attn_mask + ) + if not last_state_only: + inner_states.append(x) + + sentence_rep = x[0, :, :] + + if last_state_only: + inner_states = [x] + + if self.traceable: + return torch.stack(inner_states), sentence_rep + else: + return inner_states, sentence_rep diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_sentence_encoder_layer.py b/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_sentence_encoder_layer.py new file mode 100644 index 00000000..f869c4b2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/transformer_sentence_encoder_layer.py @@ -0,0 +1,139 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Callable, Optional + +import torch +import torch.nn as nn +from fairseq import utils +from fairseq.modules import LayerNorm, MultiheadAttention +from fairseq.modules.fairseq_dropout import FairseqDropout +from fairseq.modules.quant_noise import quant_noise + + +class TransformerSentenceEncoderLayer(nn.Module): + """ + Implements a Transformer Encoder Layer used in BERT/XLM style pre-trained + models. + """ + + def __init__( + self, + embedding_dim: int = 768, + ffn_embedding_dim: int = 3072, + num_attention_heads: int = 8, + dropout: float = 0.1, + attention_dropout: float = 0.1, + activation_dropout: float = 0.1, + activation_fn: str = "relu", + export: bool = False, + q_noise: float = 0.0, + qn_block_size: int = 8, + init_fn: Callable = None, + ) -> None: + super().__init__() + + if init_fn is not None: + init_fn() + + # Initialize parameters + self.embedding_dim = embedding_dim + self.num_attention_heads = num_attention_heads + self.attention_dropout = attention_dropout + self.q_noise = q_noise + self.qn_block_size = qn_block_size + + self.dropout_module = FairseqDropout( + dropout, module_name=self.__class__.__name__ + ) + self.activation_dropout_module = FairseqDropout( + activation_dropout, module_name=self.__class__.__name__ + ) + + # Initialize blocks + self.activation_fn = utils.get_activation_fn(activation_fn) + self.self_attn = self.build_self_attention( + self.embedding_dim, + num_attention_heads, + dropout=attention_dropout, + self_attention=True, + q_noise=q_noise, + qn_block_size=qn_block_size, + ) + + # layer norm associated with the self attention layer + self.self_attn_layer_norm = LayerNorm(self.embedding_dim, export=export) + + self.fc1 = self.build_fc1( + self.embedding_dim, + ffn_embedding_dim, + q_noise=q_noise, + qn_block_size=qn_block_size, + ) + self.fc2 = self.build_fc2( + ffn_embedding_dim, + self.embedding_dim, + q_noise=q_noise, + qn_block_size=qn_block_size, + ) + + # layer norm associated with the position wise feed-forward NN + self.final_layer_norm = LayerNorm(self.embedding_dim, export=export) + + def build_fc1(self, input_dim, output_dim, q_noise, qn_block_size): + return quant_noise(nn.Linear(input_dim, output_dim), q_noise, qn_block_size) + + def build_fc2(self, input_dim, output_dim, q_noise, qn_block_size): + return quant_noise(nn.Linear(input_dim, output_dim), q_noise, qn_block_size) + + def build_self_attention( + self, + embed_dim, + num_attention_heads, + dropout, + self_attention, + q_noise, + qn_block_size, + ): + return MultiheadAttention( + embed_dim, + num_attention_heads, + dropout=dropout, + self_attention=True, + q_noise=q_noise, + qn_block_size=qn_block_size, + ) + + def forward( + self, + x: torch.Tensor, + self_attn_mask: Optional[torch.Tensor] = None, + self_attn_padding_mask: Optional[torch.Tensor] = None, + ): + """ + LayerNorm is applied either before or after the self-attention/ffn + modules similar to the original Transformer implementation. + """ + residual = x + x, attn = self.self_attn( + query=x, + key=x, + value=x, + key_padding_mask=self_attn_padding_mask, + need_weights=False, + attn_mask=self_attn_mask, + ) + x = self.dropout_module(x) + x = residual + x + x = self.self_attn_layer_norm(x) + + residual = x + x = self.activation_fn(self.fc1(x)) + x = self.activation_dropout_module(x) + x = self.fc2(x) + x = self.dropout_module(x) + x = residual + x + x = self.final_layer_norm(x) + return x, attn diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/transpose_last.py b/PyTorch/NLP/new-Transformer/fairseq/modules/transpose_last.py new file mode 100644 index 00000000..e578b3ec --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/transpose_last.py @@ -0,0 +1,20 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +transpose last 2 dimensions of the input +""" + +import torch.nn as nn + + +class TransposeLast(nn.Module): + def __init__(self, deconstruct_idx=None): + super().__init__() + self.deconstruct_idx = deconstruct_idx + + def forward(self, x): + if self.deconstruct_idx is not None: + x = x[self.deconstruct_idx] + return x.transpose(-2, -1) diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/unfold.py b/PyTorch/NLP/new-Transformer/fairseq/modules/unfold.py new file mode 100644 index 00000000..138272f1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/unfold.py @@ -0,0 +1,19 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.nn.functional as F + + +def unfold1d(x, kernel_size, padding_l, pad_value=0): + """unfold T x B x C to T x B x C x K""" + if kernel_size > 1: + T, B, C = x.size() + x = F.pad( + x, (0, 0, 0, 0, padding_l, kernel_size - 1 - padding_l), value=pad_value + ) + x = x.as_strided((T, B, C, kernel_size), (B * C, C, 1, B * C)) + else: + x = x.unsqueeze(3) + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/modules/vggblock.py b/PyTorch/NLP/new-Transformer/fairseq/modules/vggblock.py new file mode 100644 index 00000000..ee5ee19a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/modules/vggblock.py @@ -0,0 +1,116 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from __future__ import absolute_import, division, print_function, unicode_literals + +from collections.abc import Iterable +from itertools import repeat + +import torch +import torch.nn as nn + + +def _pair(v): + if isinstance(v, Iterable): + assert len(v) == 2, "len(v) != 2" + return v + return tuple(repeat(v, 2)) + + +def infer_conv_output_dim(conv_op, input_dim, sample_inchannel): + sample_seq_len = 200 + sample_bsz = 10 + x = torch.randn(sample_bsz, sample_inchannel, sample_seq_len, input_dim) + # N x C x H x W + # N: sample_bsz, C: sample_inchannel, H: sample_seq_len, W: input_dim + x = conv_op(x) + # N x C x H x W + x = x.transpose(1, 2) + # N x H x C x W + bsz, seq = x.size()[:2] + per_channel_dim = x.size()[3] + # bsz: N, seq: H, CxW the rest + return x.contiguous().view(bsz, seq, -1).size(-1), per_channel_dim + + +class VGGBlock(torch.nn.Module): + """ + VGG motibated cnn module https://arxiv.org/pdf/1409.1556.pdf + + Args: + in_channels: (int) number of input channels (typically 1) + out_channels: (int) number of output channels + conv_kernel_size: convolution channels + pooling_kernel_size: the size of the pooling window to take a max over + num_conv_layers: (int) number of convolution layers + input_dim: (int) input dimension + conv_stride: the stride of the convolving kernel. + Can be a single number or a tuple (sH, sW) Default: 1 + padding: implicit paddings on both sides of the input. + Can be a single number or a tuple (padH, padW). Default: None + layer_norm: (bool) if layer norm is going to be applied. Default: False + + Shape: + Input: BxCxTxfeat, i.e. (batch_size, input_size, timesteps, features) + Output: BxCxTxfeat, i.e. (batch_size, input_size, timesteps, features) + """ + + def __init__( + self, + in_channels, + out_channels, + conv_kernel_size, + pooling_kernel_size, + num_conv_layers, + input_dim, + conv_stride=1, + padding=None, + layer_norm=False, + ): + assert ( + input_dim is not None + ), "Need input_dim for LayerNorm and infer_conv_output_dim" + super(VGGBlock, self).__init__() + self.in_channels = in_channels + self.out_channels = out_channels + self.conv_kernel_size = _pair(conv_kernel_size) + self.pooling_kernel_size = _pair(pooling_kernel_size) + self.num_conv_layers = num_conv_layers + self.padding = ( + tuple(e // 2 for e in self.conv_kernel_size) + if padding is None + else _pair(padding) + ) + self.conv_stride = _pair(conv_stride) + + self.layers = nn.ModuleList() + for layer in range(num_conv_layers): + conv_op = nn.Conv2d( + in_channels if layer == 0 else out_channels, + out_channels, + self.conv_kernel_size, + stride=self.conv_stride, + padding=self.padding, + ) + self.layers.append(conv_op) + if layer_norm: + conv_output_dim, per_channel_dim = infer_conv_output_dim( + conv_op, input_dim, in_channels if layer == 0 else out_channels + ) + self.layers.append(nn.LayerNorm(per_channel_dim)) + input_dim = per_channel_dim + self.layers.append(nn.ReLU()) + + if self.pooling_kernel_size is not None: + pool_op = nn.MaxPool2d(kernel_size=self.pooling_kernel_size, ceil_mode=True) + self.layers.append(pool_op) + self.total_output_dim, self.output_dim = infer_conv_output_dim( + pool_op, input_dim, out_channels + ) + + def forward(self, x): + for i, _ in enumerate(self.layers): + x = self.layers[i](x) + return x diff --git a/PyTorch/NLP/new-Transformer/fairseq/nan_detector.py b/PyTorch/NLP/new-Transformer/fairseq/nan_detector.py new file mode 100644 index 00000000..7d46d766 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/nan_detector.py @@ -0,0 +1,108 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch + + +logger = logging.getLogger(__name__) + + +class NanDetector: + """ + Detects the first NaN or Inf in forward and/or backward pass and logs, together with the module name + """ + + def __init__(self, model, forward=True, backward=True): + self.bhooks = [] + self.fhooks = [] + self.forward = forward + self.backward = backward + self.named_parameters = list(model.named_parameters()) + self.reset() + + for name, mod in model.named_modules(): + mod.__module_name = name + self.add_hooks(mod) + + def __enter__(self): + return self + + def __exit__(self, exc_type, exc_value, exc_traceback): + # Dump out all model gnorms to enable better debugging + norm = {} + gradients = {} + for name, param in self.named_parameters: + if param.grad is not None: + grad_norm = torch.norm(param.grad.data.float(), p=2) + norm[name] = grad_norm.item() + if torch.isnan(grad_norm).any() or torch.isinf(grad_norm).any(): + gradients[name] = param.grad.data + if len(gradients) > 0: + logger.info("Detected nan/inf grad norm, dumping norms...") + logger.info(f"norms: {norm}") + logger.info(f"gradients: {gradients}") + + self.close() + + def add_hooks(self, module): + if self.forward: + self.fhooks.append(module.register_forward_hook(self.fhook_fn)) + if self.backward: + self.bhooks.append(module.register_backward_hook(self.bhook_fn)) + + def reset(self): + self.has_printed_f = False + self.has_printed_b = False + + def _detect(self, tensor, name, backward): + err = None + if ( + torch.is_floating_point(tensor) + # single value tensors (like the loss) will not provide much info + and tensor.numel() >= 2 + ): + with torch.no_grad(): + if torch.isnan(tensor).any(): + err = "NaN" + elif torch.isinf(tensor).any(): + err = "Inf" + if err is not None: + err = f"{err} detected in output of {name}, shape: {tensor.shape}, {'backward' if backward else 'forward'}" + return err + + def _apply(self, module, inp, x, backward): + if torch.is_tensor(x): + if isinstance(inp, tuple) and len(inp) > 0: + inp = inp[0] + err = self._detect(x, module.__module_name, backward) + if err is not None: + if torch.is_tensor(inp) and not backward: + err += ( + f" input max: {inp.max().item()}, input min: {inp.min().item()}" + ) + + has_printed_attr = "has_printed_b" if backward else "has_printed_f" + logger.warning(err) + setattr(self, has_printed_attr, True) + elif isinstance(x, dict): + for v in x.values(): + self._apply(module, inp, v, backward) + elif isinstance(x, list) or isinstance(x, tuple): + for v in x: + self._apply(module, inp, v, backward) + + def fhook_fn(self, module, inp, output): + if not self.has_printed_f: + self._apply(module, inp, output, backward=False) + + def bhook_fn(self, module, inp, output): + if not self.has_printed_b: + self._apply(module, inp, output, backward=True) + + def close(self): + for hook in self.fhooks + self.bhooks: + hook.remove() diff --git a/PyTorch/NLP/new-Transformer/fairseq/ngram_repeat_block.py b/PyTorch/NLP/new-Transformer/fairseq/ngram_repeat_block.py new file mode 100644 index 00000000..4eb50303 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/ngram_repeat_block.py @@ -0,0 +1,120 @@ +# Originally from Microsoft Corporation. +# Licensed under the MIT License. + +""" Wrapper for ngram_repeat_block cuda extension """ +import math +import warnings +from typing import List + +import torch +from torch import nn + +try: + from fairseq import ngram_repeat_block_cuda + + EXTENSION_BUILT = True +except ImportError: + EXTENSION_BUILT = False + + +def is_cuda_extension_usable() -> bool: + """Check whether ngram_repeat_block_cuda is built properly""" + if not EXTENSION_BUILT or not torch.cuda.is_available(): + return False + bsz = 2 + tokens = torch.tensor([[4, 4, 3, 2], [1, 2, 3, 4]], dtype=torch.long, device="cuda") + lprobs = torch.rand((8, 12), device="cuda") + try: + outputs = ngram_repeat_block_cuda.forward(tokens, lprobs, bsz, 3, 4, 3) + outputs = outputs + 4 # This line breaks if the extension is built incorrectly. + return True + except RuntimeError: + warnings.warn( + "NGramRepeatBlock extension must be rebuilt." + 'Run TORCH_CUDA_ARCH_LIST="6.0;6.1;7.0" python setup.py build_ext --inplace' + ) + return False + + +class NGramRepeatBlock(nn.Module): + """Wrapper class for calling ngram_repeat_block cuda extension""" + + def __init__(self, no_repeat_ngram_size: int, use_extension: bool = True): + super().__init__() + self.use_extension = is_cuda_extension_usable() if use_extension else False + self.no_repeat_ngram_size = no_repeat_ngram_size + + def reset_parameters(self): + pass + + @torch.jit.unused + def call_cuda_extension( + self, + tokens, + lprobs, + bsz: int, + beam_size: int, + step: int, + ): + return ngram_repeat_block_cuda.forward( + tokens, lprobs, bsz, step, beam_size, self.no_repeat_ngram_size + ) + + def forward( + self, + tokens, + lprobs, + bsz: int, + beam_size: int, + step: int, + ): + """ + Args: + tokens(Tensor): Input tokens(Bsz*beam, seq_len) + lprobs(Tensor): likelihood probability, + Expected to be updated in place.(Bsz*beam, vocab_size) + bsz(int): batch size + step(int): current step + beam_size(int): beam size + no_repeat_ngram_size(int): Ngram size + """ + msg = f"expected {bsz *beam_size} got" + assert tokens.size(0) == bsz * beam_size, f"{msg} {tokens.size(0)}" + assert lprobs.size(0) == bsz * beam_size, f"{msg} {lprobs.size(0)}" + if self.use_extension: + return self.call_cuda_extension(tokens, lprobs, bsz, beam_size, step) + + else: + return self._no_repeat_ngram( + tokens, + lprobs, + bsz, + beam_size, + step, + ) + + def _no_repeat_ngram(self, tokens, lprobs, bsz: int, beam_size: int, step: int): + """For each hypothesis generate a list of previous ngrams and set associated lprobs to -inf""" + banned_tokens = [ + torch.jit.annotate(List[int], []) for bbsz_idx in range(bsz * beam_size) + ] + if step + 2 - self.no_repeat_ngram_size >= 0: + cpu_tokens: List[List[int]] = tokens.cpu().tolist() + check_start_pos = step + 2 - self.no_repeat_ngram_size + for bbsz_idx in range(bsz * beam_size): + ngram_to_check = cpu_tokens[bbsz_idx][ + -(self.no_repeat_ngram_size - 1) : + ] + for i in range(check_start_pos): + if ( + ngram_to_check + == cpu_tokens[bbsz_idx][i : i + self.no_repeat_ngram_size - 1] + ): + banned_tokens[bbsz_idx].append( + cpu_tokens[bbsz_idx][i + self.no_repeat_ngram_size - 1] + ) + for bbsz_idx in range(bsz * beam_size): + lprobs[bbsz_idx][ + torch.tensor(banned_tokens[bbsz_idx], dtype=torch.int64) + ] = torch.tensor(-math.inf).to(lprobs) + return lprobs diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/optim/__init__.py new file mode 100644 index 00000000..be783be8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/__init__.py @@ -0,0 +1,48 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +import importlib +import os + +from fairseq import registry +from fairseq.optim.bmuf import FairseqBMUF # noqa +from fairseq.optim.fairseq_optimizer import ( # noqa + FairseqOptimizer, + LegacyFairseqOptimizer, +) +from fairseq.optim.amp_optimizer import AMPOptimizer +from fairseq.optim.fp16_optimizer import FP16Optimizer, MemoryEfficientFP16Optimizer +from fairseq.optim.shard import shard_ +from omegaconf import DictConfig + +__all__ = [ + "AMPOptimizer", + "FairseqOptimizer", + "FP16Optimizer", + "MemoryEfficientFP16Optimizer", + "shard_", +] + +( + _build_optimizer, + register_optimizer, + OPTIMIZER_REGISTRY, + OPTIMIZER_DATACLASS_REGISTRY, +) = registry.setup_registry("--optimizer", base_class=FairseqOptimizer, required=True) + + +def build_optimizer(cfg: DictConfig, params, *extra_args, **extra_kwargs): + if all(isinstance(p, dict) for p in params): + params = [t for p in params for t in p.values()] + params = list(filter(lambda p: p.requires_grad, params)) + return _build_optimizer(cfg, params, *extra_args, **extra_kwargs) + + +# automatically import any Python files in the optim/ directory +for file in sorted(os.listdir(os.path.dirname(__file__))): + if file.endswith(".py") and not file.startswith("_"): + file_name = file[: file.find(".py")] + importlib.import_module("fairseq.optim." + file_name) diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/adadelta.py b/PyTorch/NLP/new-Transformer/fairseq/optim/adadelta.py new file mode 100644 index 00000000..f1a21549 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/adadelta.py @@ -0,0 +1,47 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.optim + +from . import LegacyFairseqOptimizer, register_optimizer + + +@register_optimizer("adadelta") +class Adadelta(LegacyFairseqOptimizer): + def __init__(self, args, params): + super().__init__(args) + self._optimizer = torch.optim.Adadelta(params, **self.optimizer_config) + + @staticmethod + def add_args(parser): + """Add optimizer-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--adadelta-rho', type=float, default=0.9, metavar='RHO', + help='coefficient used for computing a running average of squared gradients') + parser.add_argument('--adadelta-eps', type=float, default=1e-6, metavar='EPS', + help='term added to the denominator to improve numerical stability') + parser.add_argument('--weight-decay', '--wd', default=0.0, type=float, metavar='WD', + help='weight decay') + parser.add_argument('--anneal-eps', action='store_true', help='flag to anneal eps') + # fmt: on + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + return { + "lr": self.args.lr[0], + "rho": self.args.adadelta_rho, + "eps": self.args.adadelta_eps, + "weight_decay": self.args.weight_decay, + } + + @property + def supports_flat_params(self): + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/adafactor.py b/PyTorch/NLP/new-Transformer/fairseq/optim/adafactor.py new file mode 100644 index 00000000..042ae926 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/adafactor.py @@ -0,0 +1,268 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math + +import torch +import torch.optim + +from . import LegacyFairseqOptimizer, register_optimizer + + +@register_optimizer("adafactor") +class FairseqAdafactor(LegacyFairseqOptimizer): + def __init__(self, args, params): + super().__init__(args) + self._optimizer = Adafactor(params, **self.optimizer_config) + + @staticmethod + def add_args(parser): + """Add optimizer-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--adafactor-eps', default='(1e-30, 1e-3)', metavar="E", + help='epsilons for Adafactor optimizer') + parser.add_argument('--clip-threshold', type=float, default=1.0, metavar="C", + help='threshold for clipping update root mean square') + parser.add_argument('--decay-rate', type=float, default=-0.8, metavar="D", + help='decay rate of the second moment estimator') + parser.add_argument('--beta1', type=float, default=None, metavar="B", + help='beta for first moment estimator. Optional') + parser.add_argument('--weight-decay', '--wd', default=0.0, type=float, metavar='WD', + help='weight decay') + parser.add_argument('--scale-parameter', action='store_true', + help='scale learning rate by root mean square of parameter') + parser.add_argument('--relative-step', action='store_true', + help='set learning rate to inverse square root of timestep,' + 'otherwise use external learning rate') + parser.add_argument('--warmup-init', action='store_true', + help='use relative step for warm-up learning rate schedule') + # fmt: on + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + Note : Convergence issues empirically observed with fp16 on. + Might require search for appropriate configuration. + """ + return { + "lr": self.args.lr[0], + "eps": eval(self.args.adafactor_eps), + "clip_threshold": self.args.clip_threshold, + "decay_rate": self.args.decay_rate, + "beta1": self.args.beta1, + "weight_decay": self.args.weight_decay, + "scale_parameter": self.args.scale_parameter, # defaults to False + "relative_step": self.args.relative_step, # defaults to False + "warmup_init": self.args.warmup_init, + } + + +class Adafactor(torch.optim.Optimizer): + """Implements Adafactor algorithm. + + This implementation is based on: + `Adafactor: Adaptive Learning Rates with Sublinear Memory Cost` + (see https://arxiv.org/abs/1804.04235) + + Note that this optimizer internally adjusts the learning rate + depending on the *scale_parameter*, *relative_step* and + *warmup_init* options. To use a manual (external) learning rate + schedule you should set `scale_parameter=False` and + `relative_step=False`. + + Args: + params (iterable): iterable of parameters to optimize or dicts defining + parameter groups + lr (float, optional): external learning rate (default: None) + eps (tuple[float, float]): regularization constans for square gradient + and parameter scale respectively (default: (1e-30, 1e-3)) + clip_threshold (float): threshold of root mean square of + final gradient update (default: 1.0) + decay_rate (float): coefficient used to compute running averages of square + gradient (default: -0.8) + beta1 (float): coefficient used for computing running averages of gradient + (default: None) + weight_decay (float, optional): weight decay (L2 penalty) (default: 0) + scale_parameter (bool): if True, learning rate is scaled by root mean square of + parameter (default: True) + relative_step (bool): if True, time-dependent learning rate is computed + instead of external learning rate (default: True) + warmup_init (bool): time-dependent learning rate computation depends on + whether warm-up initialization is being used (default: False) + """ + + def __init__( + self, + params, + lr=None, + eps=(1e-30, 1e-3), + clip_threshold=1.0, + decay_rate=-0.8, + beta1=None, + weight_decay=0.0, + scale_parameter=True, + relative_step=True, + warmup_init=False, + ): + if lr is not None and relative_step: + raise ValueError("Cannot combine manual lr and relative_step options") + if warmup_init and not relative_step: + raise ValueError("warmup_init requires relative_step=True") + + defaults = dict( + lr=lr, + eps=eps, + clip_threshold=clip_threshold, + decay_rate=decay_rate, + beta1=beta1, + weight_decay=weight_decay, + scale_parameter=scale_parameter, + relative_step=relative_step, + warmup_init=warmup_init, + ) + super(Adafactor, self).__init__(params, defaults) + + @property + def supports_memory_efficient_fp16(self): + return True + + @property + def supports_flat_params(self): + return False + + def _get_lr(self, param_group, param_state): + rel_step_sz = param_group["lr"] + if param_group["relative_step"]: + min_step = ( + 1e-6 * param_state["step"] if param_group["warmup_init"] else 1e-2 + ) + rel_step_sz = min(min_step, 1.0 / math.sqrt(param_state["step"])) + param_scale = 1.0 + if param_group["scale_parameter"]: + param_scale = max(param_group["eps"][1], param_state["RMS"]) + return param_scale * rel_step_sz + + def _get_options(self, param_group, param_shape): + factored = len(param_shape) >= 2 + use_first_moment = param_group["beta1"] is not None + return factored, use_first_moment + + def _rms(self, tensor): + return tensor.norm(2) / (tensor.numel() ** 0.5) + + def _approx_sq_grad(self, exp_avg_sq_row, exp_avg_sq_col): + r_factor = ( + (exp_avg_sq_row / exp_avg_sq_row.mean(dim=-1, keepdim=True)) + .rsqrt_() + .unsqueeze(-1) + ) + c_factor = exp_avg_sq_col.unsqueeze(-2).rsqrt() + return torch.mul(r_factor, c_factor) + + def step(self, closure=None): + """Performs a single optimization step. + + Args: + closure (callable, optional): A closure that reevaluates the model + and returns the loss. + """ + loss = None + if closure is not None: + loss = closure() + + for group in self.param_groups: + for p in group["params"]: + if p.grad is None: + continue + grad = p.grad.data + if grad.dtype in {torch.float16, torch.bfloat16}: + grad = grad.float() + if grad.is_sparse: + raise RuntimeError("Adafactor does not support sparse gradients.") + + state = self.state[p] + grad_shape = grad.shape + + factored, use_first_moment = self._get_options(group, grad_shape) + # State Initialization + if len(state) == 0: + state["step"] = 0 + + if use_first_moment: + # Exponential moving average of gradient values + state["exp_avg"] = torch.zeros_like(grad) + if factored: + state["exp_avg_sq_row"] = torch.zeros(grad_shape[:-1]).to(grad) + state["exp_avg_sq_col"] = torch.zeros( + grad_shape[:-2] + grad_shape[-1:] + ).to(grad) + else: + state["exp_avg_sq"] = torch.zeros_like(grad) + + state["RMS"] = 0 + else: + if use_first_moment: + state["exp_avg"] = state["exp_avg"].to(grad) + if factored: + state["exp_avg_sq_row"] = state["exp_avg_sq_row"].to(grad) + state["exp_avg_sq_col"] = state["exp_avg_sq_col"].to(grad) + else: + state["exp_avg_sq"] = state["exp_avg_sq"].to(grad) + + p_data_fp32 = p.data + if p.data.dtype in {torch.float16, torch.bfloat16}: + p_data_fp32 = p_data_fp32.float() + + state["step"] += 1 + state["RMS"] = self._rms(p_data_fp32) + group["lr"] = self._get_lr(group, state) + + beta2t = 1.0 - math.pow(state["step"], group["decay_rate"]) + update = (grad**2) + group["eps"][0] + if factored: + exp_avg_sq_row = state["exp_avg_sq_row"] + exp_avg_sq_col = state["exp_avg_sq_col"] + + exp_avg_sq_row.mul_(beta2t).add_( + update.mean(dim=-1), alpha=1.0 - beta2t + ) + exp_avg_sq_col.mul_(beta2t).add_( + update.mean(dim=-2), alpha=1.0 - beta2t + ) + + # Approximation of exponential moving average of square of gradient + update = self._approx_sq_grad(exp_avg_sq_row, exp_avg_sq_col) + update.mul_(grad) + else: + exp_avg_sq = state["exp_avg_sq"] + + exp_avg_sq.mul_(beta2t).add_(update, alpha=1.0 - beta2t) + update = exp_avg_sq.rsqrt().mul_(grad) + + update.div_( + (self._rms(update) / group["clip_threshold"]).clamp_(min=1.0) + ) + update.mul_(group["lr"]) + + if use_first_moment: + exp_avg = state["exp_avg"] + exp_avg.mul_(group["beta1"]).add_(update, alpha=1 - group["beta1"]) + update = exp_avg + + if group["weight_decay"] != 0: + p_data_fp32.add_( + p_data_fp32, alpha=-group["weight_decay"] * group["lr"] + ) + + p_data_fp32.add_(-update) + + if p.data.dtype in {torch.float16, torch.bfloat16}: + p.data.copy_(p_data_fp32) + + return loss diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/adagrad.py b/PyTorch/NLP/new-Transformer/fairseq/optim/adagrad.py new file mode 100644 index 00000000..4f539541 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/adagrad.py @@ -0,0 +1,40 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.optim + +from . import LegacyFairseqOptimizer, register_optimizer + + +@register_optimizer("adagrad") +class Adagrad(LegacyFairseqOptimizer): + def __init__(self, args, params): + super().__init__(args) + self._optimizer = torch.optim.Adagrad(params, **self.optimizer_config) + + @staticmethod + def add_args(parser): + """Add optimizer-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--weight-decay', '--wd', default=0.0, type=float, metavar='WD', + help='weight decay') + # fmt: on + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + return { + "lr": self.args.lr[0], + "weight_decay": self.args.weight_decay, + } + + @property + def supports_flat_params(self): + return False diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/adam.py b/PyTorch/NLP/new-Transformer/fairseq/optim/adam.py new file mode 100644 index 00000000..678ec7c6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/adam.py @@ -0,0 +1,239 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import math +from collections.abc import Collection +from dataclasses import dataclass, field +from typing import Any, List + +import torch +import torch.distributed as dist +import torch.optim +from fairseq.dataclass import FairseqDataclass +from fairseq.optim import FairseqOptimizer, register_optimizer +from fairseq.optim.fused_adam import get_fused_adam_class +from omegaconf import II, OmegaConf + + +logger = logging.getLogger(__name__) + + +@dataclass +class FairseqAdamConfig(FairseqDataclass): + adam_betas: Any = field( + default=(0.9, 0.999), metadata={"help": "betas for Adam optimizer"} + ) + adam_eps: float = field( + default=1e-8, metadata={"help": "epsilon for Adam optimizer"} + ) + weight_decay: float = field(default=0.0, metadata={"help": "weight decay"}) + use_old_adam: bool = field( + default=False, metadata={"help": "Use fairseq.optim.adam.Adam"} + ) + fp16_adam_stats: bool = field( + default=False, metadata={"help": "use FP16 stats (with automatic scaling)"} + ) + # TODO common vars below in parent + tpu: bool = II("common.tpu") + lr: List[float] = II("optimization.lr") + + +@register_optimizer("adam", dataclass=FairseqAdamConfig) +class FairseqAdam(FairseqOptimizer): + """Adam optimizer for fairseq. + + Important note: this optimizer corresponds to the "AdamW" variant of + Adam in its weight decay behavior. As such, it is most closely + analogous to torch.optim.AdamW from PyTorch. + """ + + def __init__(self, cfg: FairseqAdamConfig, params): + super().__init__(cfg) + fused_adam_cls = get_fused_adam_class() + use_fused_adam = ( + not getattr(cfg, "use_old_adam", False) + and fused_adam_cls is not None + and torch.cuda.is_available() + ) + if getattr(cfg, "tpu", False): + if self.cfg.fp16_adam_stats: + raise NotImplementedError("--fp16-adam-stats is only supported on GPU") + # on TPUs we use the Adam defined here, since it + # automatically casts gradients to FP32 + self._optimizer = Adam(params, **self.optimizer_config) + elif use_fused_adam: + logger.info("using FusedAdam") + self._optimizer = fused_adam_cls( + params, use_fp16_stats=self.cfg.fp16_adam_stats, **self.optimizer_config + ) + else: + if self.cfg.fp16_adam_stats: + raise NotImplementedError( + "--fp16-adam-stats is only supported with FusedAdamV1" + ) + self._optimizer = Adam(params, **self.optimizer_config) + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + return { + "lr": self.cfg.lr[0] + if isinstance(self.cfg.lr, Collection) + else self.cfg.lr, + "betas": eval(self.cfg.adam_betas) + if isinstance(self.cfg.adam_betas, str) + else OmegaConf.to_container(self.cfg.adam_betas), + "eps": self.cfg.adam_eps, + "weight_decay": self.cfg.weight_decay, + } + + def average_params(self): + """Reduce Params is only used during BMUF distributed training.""" + state_dict = self.optimizer.state_dict() + total_gpus = float(dist.get_world_size()) + + for _, value in state_dict["state"].items(): + value["exp_avg"] /= total_gpus + value["exp_avg_sq"] /= total_gpus + dist.all_reduce(value["exp_avg"], op=dist.ReduceOp.SUM) + dist.all_reduce(value["exp_avg_sq"], op=dist.ReduceOp.SUM) + + +class Adam(torch.optim.Optimizer): + r"""Implements Adam algorithm. + + This implementation is modified from torch.optim.Adam based on: + `Fixed Weight Decay Regularization in Adam` + (see https://arxiv.org/abs/1711.05101) + + It has been proposed in `Adam: A Method for Stochastic Optimization`_. + + Args: + params (iterable): iterable of parameters to optimize or dicts defining + parameter groups + lr (float, optional): learning rate (default: 1e-3) + betas (Tuple[float, float], optional): coefficients used for computing + running averages of gradient and its square (default: (0.9, 0.999)) + eps (float, optional): term added to the denominator to improve + numerical stability (default: 1e-8) + weight_decay (float, optional): weight decay (L2 penalty) (default: 0) + amsgrad (boolean, optional): whether to use the AMSGrad variant of this + algorithm from the paper `On the Convergence of Adam and Beyond`_ + + .. _Adam\: A Method for Stochastic Optimization: + https://arxiv.org/abs/1412.6980 + .. _On the Convergence of Adam and Beyond: + https://openreview.net/forum?id=ryQu7f-RZ + """ + + def __init__( + self, + params, + lr=1e-3, + betas=(0.9, 0.999), + eps=1e-8, + weight_decay=0, + amsgrad=False, + ): + defaults = dict( + lr=lr, betas=betas, eps=eps, weight_decay=weight_decay, amsgrad=amsgrad + ) + super(Adam, self).__init__(params, defaults) + + @property + def supports_memory_efficient_fp16(self): + return True + + @property + def supports_flat_params(self): + return True + + def step(self, closure=None): + """Performs a single optimization step. + + Args: + closure (callable, optional): A closure that reevaluates the model + and returns the loss. + """ + loss = None + if closure is not None: + loss = closure() + + for group in self.param_groups: + for p in group["params"]: + if p.grad is None: + continue + grad = p.grad.data + if grad.dtype in {torch.float16, torch.bfloat16}: + grad = grad.float() + if grad.is_sparse: + raise RuntimeError( + "Adam does not support sparse gradients, please consider SparseAdam instead" + ) + amsgrad = group.get("amsgrad", False) + + p_data_fp32 = p.data + if p.data.dtype in {torch.float16, torch.bfloat16}: + p_data_fp32 = p_data_fp32.float() + + state = self.state[p] + + # State initialization + if len(state) == 0: + state["step"] = 0 + # Exponential moving average of gradient values + state["exp_avg"] = torch.zeros_like(p_data_fp32) + # Exponential moving average of squared gradient values + state["exp_avg_sq"] = torch.zeros_like(p_data_fp32) + if amsgrad: + # Maintains max of all exp. moving avg. of sq. grad. values + state["max_exp_avg_sq"] = torch.zeros_like(p_data_fp32) + else: + state["exp_avg"] = state["exp_avg"].to(p_data_fp32) + state["exp_avg_sq"] = state["exp_avg_sq"].to(p_data_fp32) + if amsgrad: + state["max_exp_avg_sq"] = state["max_exp_avg_sq"].to( + p_data_fp32 + ) + + exp_avg, exp_avg_sq = state["exp_avg"], state["exp_avg_sq"] + if amsgrad: + max_exp_avg_sq = state["max_exp_avg_sq"] + beta1, beta2 = group["betas"] + + state["step"] += 1 + + # Decay the first and second moment running average coefficient + exp_avg.mul_(beta1).add_(grad, alpha=1 - beta1) + exp_avg_sq.mul_(beta2).addcmul_(grad, grad, value=1 - beta2) + if amsgrad: + # Maintains the maximum of all 2nd moment running avg. till now + torch.max(max_exp_avg_sq, exp_avg_sq, out=max_exp_avg_sq) + # Use the max. for normalizing running avg. of gradient + denom = max_exp_avg_sq.sqrt().add_(group["eps"]) + else: + denom = exp_avg_sq.sqrt().add_(group["eps"]) + + bias_correction1 = 1 - beta1 ** state["step"] + bias_correction2 = 1 - beta2 ** state["step"] + step_size = group["lr"] * math.sqrt(bias_correction2) / bias_correction1 + + if group["weight_decay"] != 0: + p_data_fp32.add_( + p_data_fp32, alpha=-group["weight_decay"] * group["lr"] + ) + + p_data_fp32.addcdiv_(exp_avg, denom, value=-step_size) + + if p.data.dtype in {torch.float16, torch.bfloat16}: + p.data.copy_(p_data_fp32) + + return loss diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/adamax.py b/PyTorch/NLP/new-Transformer/fairseq/optim/adamax.py new file mode 100644 index 00000000..98ff8ad7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/adamax.py @@ -0,0 +1,172 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import torch.optim + +from . import LegacyFairseqOptimizer, register_optimizer + + +@register_optimizer("adamax") +class FairseqAdamax(LegacyFairseqOptimizer): + def __init__(self, args, params): + super().__init__(args) + self._optimizer = Adamax(params, **self.optimizer_config) + + @staticmethod + def add_args(parser): + """Add optimizer-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--adamax-betas', default='(0.9, 0.999)', metavar='B', + help='betas for Adam optimizer') + parser.add_argument('--adamax-eps', type=float, default=1e-8, metavar='D', + help='epsilon for Adam optimizer') + parser.add_argument('--weight-decay', '--wd', default=0.0, type=float, metavar='WD', + help='weight decay') + parser.add_argument('--no-bias-correction', default=False, action='store_true', + help='disable bias correction') + # fmt: on + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + return { + "lr": self.args.lr[0], + "betas": eval(self.args.adamax_betas), + "eps": self.args.adamax_eps, + "weight_decay": self.args.weight_decay, + "bias_correction": not self.args.no_bias_correction, + } + + +class Adamax(torch.optim.Optimizer): + """Implements Adamax algorithm (a variant of Adam based on infinity norm). + + It has been proposed in `Adam: A Method for Stochastic Optimization`__. + + Compared to the version in PyTorch, this version implements a fix for weight decay. + + Args: + params (iterable): iterable of parameters to optimize or dicts defining + parameter groups + lr (float, optional): learning rate (default: 2e-3) + betas (Tuple[float, float], optional): coefficients used for computing + running averages of gradient and its square + eps (float, optional): term added to the denominator to improve + numerical stability (default: 1e-8) + weight_decay (float, optional): weight decay (L2 penalty) (default: 0) + bias_correction (bool, optional): enable bias correction (default: True) + + __ https://arxiv.org/abs/1412.6980 + """ + + def __init__( + self, + params, + lr=2e-3, + betas=(0.9, 0.999), + eps=1e-8, + weight_decay=0, + bias_correction=True, + ): + if not 0.0 <= lr: + raise ValueError("Invalid learning rate: {}".format(lr)) + if not 0.0 <= eps: + raise ValueError("Invalid epsilon value: {}".format(eps)) + if not 0.0 <= betas[0] < 1.0: + raise ValueError("Invalid beta parameter at index 0: {}".format(betas[0])) + if not 0.0 <= betas[1] < 1.0: + raise ValueError("Invalid beta parameter at index 1: {}".format(betas[1])) + if not 0.0 <= weight_decay: + raise ValueError("Invalid weight_decay value: {}".format(weight_decay)) + + defaults = dict( + lr=lr, + betas=betas, + eps=eps, + weight_decay=weight_decay, + bias_correction=bias_correction, + ) + super(Adamax, self).__init__(params, defaults) + + @property + def supports_memory_efficient_fp16(self): + return True + + @property + def supports_flat_params(self): + return True + + def step(self, closure=None): + """Performs a single optimization step. + + Args: + closure (callable, optional): A closure that reevaluates the model + and returns the loss. + """ + loss = None + if closure is not None: + loss = closure() + + for group in self.param_groups: + for p in group["params"]: + if p.grad is None: + continue + grad = p.grad.data.float() + if grad.is_sparse: + raise RuntimeError("Adamax does not support sparse gradients") + + p_data_fp32 = p.data + if p.data.dtype in {torch.float16, torch.bfloat16}: + p_data_fp32 = p_data_fp32.float() + + state = self.state[p] + + # State initialization + if len(state) == 0: + state["step"] = 0 + state["exp_avg"] = torch.zeros_like(p_data_fp32) + state["exp_inf"] = torch.zeros_like(p_data_fp32) + else: + state["exp_avg"] = state["exp_avg"].to(p_data_fp32) + state["exp_inf"] = state["exp_inf"].to(p_data_fp32) + + exp_avg, exp_inf = state["exp_avg"], state["exp_inf"] + beta1, beta2 = group["betas"] + eps = group["eps"] + + state["step"] += 1 + + # Update biased first moment estimate. + exp_avg.mul_(beta1).add_(grad, alpha=1 - beta1) + + # Update the exponentially weighted infinity norm. + torch.max( + exp_inf.mul_(beta2), + grad.abs_(), + out=exp_inf, + ) + + step_size = group["lr"] + if group["bias_correction"]: + bias_correction = 1 - beta1 ** state["step"] + step_size /= bias_correction + + if group["weight_decay"] != 0: + p_data_fp32.add_( + p_data_fp32, alpha=-group["weight_decay"] * group["lr"] + ) + + p_data_fp32.addcdiv_(exp_avg, exp_inf.add(eps), value=-step_size) + + if p.data.dtype in {torch.float16, torch.bfloat16}: + p.data.copy_(p_data_fp32) + + return loss diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/amp_optimizer.py b/PyTorch/NLP/new-Transformer/fairseq/optim/amp_optimizer.py new file mode 100644 index 00000000..cfe57d07 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/amp_optimizer.py @@ -0,0 +1,106 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import torch +from fairseq import optim +from omegaconf import DictConfig + +logger = logging.getLogger(__name__) + + +class AMPOptimizer(optim.FairseqOptimizer): + """ + Wrap an *optimizer* to support AMP (automatic mixed precision) training. + """ + + def __init__(self, cfg: DictConfig, params, fp32_optimizer, **kwargs): + super().__init__(cfg.optimizer) + self.fp32_optimizer = fp32_optimizer + amp_kwargs = {"init_scale": cfg.common.fp16_init_scale} + if getattr(cfg.common, "amp_scale_window", None) is not None: + amp_kwargs["growth_interval"] = cfg.common.amp_init_scale + self._grad_scaler = torch.cuda.amp.GradScaler(**amp_kwargs) + self.min_loss_scale = cfg.common.min_loss_scale + + @classmethod + def build_optimizer(cls, cfg: DictConfig, params, **kwargs): + """ + Args: + cfg (omegaconf.DictConfig): fairseq args + params (iterable): iterable of parameters to optimize + """ + fp32_optimizer = optim.build_optimizer(cfg.optimizer, params) + return cls(cfg, params, fp32_optimizer, **kwargs) + + def backward(self, loss): + """Computes the sum of gradients of the given tensor w.r.t. graph leaves. + + Compared to :func:`fairseq.optim.FairseqOptimizer.backward`, this + function additionally dynamically scales the loss to avoid gradient + underflow. + """ + self._grad_scaler.scale(loss).backward() + + def step(self): + self.scaler.step(self.fp32_optimizer) + self.scaler.update() + + def clip_grad_norm(self, max_norm, aggregate_norm_fn=None): + """Clips gradient norm.""" + self.scaler.unscale_(self.optimizer) + grad_norm = self.fp32_optimizer.clip_grad_norm(max_norm, aggregate_norm_fn) + if not torch.isfinite(grad_norm).all(): + new_loss_scale = self.next_loss_scale + if new_loss_scale <= self.min_loss_scale: + raise FloatingPointError( + ( + "AMP: Minimum loss scale reached ({}). Your loss is probably exploding. " + "Try restarting training or use fp32. {}" + ).format(self.min_loss_scale, new_loss_scale) + ) + else: + logger.info( + "AMP: overflow detected, setting scale to " f"to {new_loss_scale}" + ) + return grad_norm + + @property + def scaler(self): + return self._grad_scaler + + @property + def next_loss_scale(self): + return self.scaler.get_scale() * self.scaler.get_backoff_factor() + + @property + def optimizer(self): + return self.fp32_optimizer.optimizer + + @optimizer.setter + def optimizer(self, optimizer): + self.fp32_optimizer.optimizer = optimizer + + @property + def lr_scheduler(self): + return getattr(self.fp32_optimizer, "lr_scheduler", None) + + @property + def optimizer_config(self): + return self.fp32_optimizer.optimizer_config + + def get_lr(self): + return self.fp32_optimizer.get_lr() + + def set_lr(self, lr): + self.fp32_optimizer.set_lr(lr) + + def all_reduce_grads(self, module): + self.fp32_optimizer.all_reduce_grads(module) + + @property + def supports_flat_params(self): + return self.fp32_optimizer.supports_flat_params diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/bmuf.py b/PyTorch/NLP/new-Transformer/fairseq/optim/bmuf.py new file mode 100644 index 00000000..d6d0e04e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/bmuf.py @@ -0,0 +1,200 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field + +import torch +import torch.distributed as dist +from fairseq.dataclass.configs import FairseqBMUFConfig +from fairseq.dataclass.utils import gen_parser_from_dataclass +from fairseq.optim.fairseq_optimizer import FairseqOptimizer + + +class FairseqBMUF(FairseqOptimizer): + """ + Implements incremental block distributed data parallelism similar to + https://ieeexplore.ieee.org/document/7472805 + + Paper title: Scalable training of deep learning machines by incremental + block training with intra-block parallel optimization and blockwise + model-update filtering + """ + + def __init__(self, cfg: FairseqBMUFConfig, optimizer): + super().__init__(cfg) + self._optimizer = optimizer + self._num_updates = 0 + self.sync_iter = cfg.global_sync_iter + self.block_momentum = cfg.block_momentum + self.block_lr = cfg.block_lr + self._reset_local_data() + self.warmup_iteration = cfg.warmup_iterations + self.use_nbm = cfg.use_nbm + self.initial_state = self._optimizer.state_dict() + self.average_sync = self.cfg.average_sync + self.world_size = self.cfg.distributed_world_size + + @staticmethod + def add_args(parser): + """Add optimizer-specific arguments to the parser.""" + gen_parser_from_dataclass(parser, FairseqBMUFConfig()) + + @property + def optimizer(self): + return self._optimizer.optimizer + + @property + def optimizer_config(self): + return self._optimizer.optimizer_config + + def get_lr(self): + return self._optimizer.get_lr() + + def set_lr(self, lr): + self._optimizer.set_lr(lr) + + def state_dict(self): + return self._optimizer.state_dict() + + def load_state_dict(self, state_dict, optimizer_overrides=None): + self._optimizer.load_state_dict(state_dict, optimizer_overrides) + self.initial_state = self._optimizer.state_dict() + + def multiply_grads(self, c): + """Multiplies grads by a constant *c*.""" + self._optimizer.multiply_grads(c) + + def clip_grad_norm(self, max_norm, aggregate_norm_fn=None): + """Clips gradient norm.""" + return self._optimizer.clip_grad_norm(max_norm, aggregate_norm_fn) + + def average_params(self): + self._optimizer.average_params() + + def _block_sync(self): + if self.world_size <= 1: + return + # Update the global model using local models from all GPUs + # (Step-1) Calculate grad between previously synced model and + # currrent local model + if self.block_momentum != 0: + self._calc_grad() + + # (Step-2) Average gradient from all GPUs + self._avg_grad_from_all_gpus() + + # (Step-3) Calculate global momentum and update the global model + if self.block_momentum != 0: + self._update_global_model() + + # (Step-4) Average local optimizer params + if self.average_sync: + self.average_params() + + def _is_warmup_end(self): + # Check whether train iterations is equal to warmup iter + if self.get_num_updates() == self.warmup_iteration: + return True + return False + + def _is_bmuf_iter(self): + # Check whether train iterations is equal to bmuf sync iter + if (self.get_num_updates() > self.warmup_iteration) and ( + self.get_num_updates() % self.sync_iter == 0 + ): + return True + return False + + def _warmup_sync(self, root_rank=0): + if self.world_size <= 1: + return + # Broadcast the local model to all gpus + for param in self.params: + dist.broadcast(param.data, src=root_rank) + + # Update local optimizer state + if self.average_sync: + self._optimizer.average_params() + else: + self._optimizer.load_state_dict(self.initial_state) + + self._reset_local_data() + + def step(self, closure=None): + """Performs a single optimization step.""" + self._optimizer.step(closure) + self.set_num_updates(self.get_num_updates() + 1) + if self._is_warmup_end(): + self._warmup_sync() + elif self._is_bmuf_iter(): + self._block_sync() + + def zero_grad(self): + """Clears the gradients of all optimized parameters.""" + self._optimizer.zero_grad() + + def get_num_updates(self): + """Get the number of parameters updates.""" + return self._num_updates + + def set_num_updates(self, num_updates): + """Set the number of parameters updates.""" + self._num_updates = num_updates + + @torch.no_grad() + def _reset_local_data(self): + # (Step-0) Initialize global momentum parameters and store global copy on each gpu + self.global_params = [torch.zeros_like(p.data) for p in self.params] + self.smoothed_grads = [p.data.new_zeros(p.data.size()) for p in self.params] + self.grads = [p.data.new_zeros(p.data.size()) for p in self.params] + + # saving the global model locally for calculating gradient during bmuf sync + for param, global_param in zip(self.params, self.global_params): + global_param.copy_(param.data) + + @torch.no_grad() + def _calc_grad(self): + # global_params is basically the global copy from the previously finished + # synchronisation. param.data is local parameter after block_sync_freq + # for the local gpu. so grad is difference between previously synced + # model and currrent local model. + for index, (param, global_param) in enumerate( + zip(self.params, self.global_params) + ): + self.grads[index] = global_param - param.data + + def _avg_grad_from_all_gpus(self): + for index, param in enumerate(self.params): + sync_para = param.data if self.block_momentum == 0 else self.grads[index] + sync_para /= float(dist.get_world_size()) + dist.all_reduce(sync_para, op=dist.ReduceOp.SUM) + + @torch.no_grad() + def _update_global_model(self): + for index, (param, global_param, smoothed_grad, grad) in enumerate( + zip( + self.params, + self.global_params, + self.smoothed_grads, + # all gpus would share the same value of smoothed_grad, since it is + # always computed on synchronized gradients. + self.grads, + ) + ): + # global_param is basically last syncrhornized parameter. though + # smoothed_grad is local, all processes will have same value of + # smoothed_grad and hence param is globally synchronized copy. + # smoothed_grad(t) = BM * smoothed_grad(t-1) + BM_lr * grad(t) + smoothed_grad = self.block_momentum * smoothed_grad + self.block_lr * grad + param.data.copy_(global_param - smoothed_grad) + + # A Nesterov momentum here is to do a partial weight update before + # calculating the gradient + if self.use_nbm: + param.data.copy_(param.data - self.block_momentum * smoothed_grad) + + # backup for the next synchronization. + self.smoothed_grads[index] = smoothed_grad + global_param.copy_(param.data) diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/composite.py b/PyTorch/NLP/new-Transformer/fairseq/optim/composite.py new file mode 100644 index 00000000..63701ee8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/composite.py @@ -0,0 +1,190 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from collections import defaultdict +from dataclasses import dataclass, field +from typing import Dict, Any, List, Optional + +import torch.optim +from fairseq.dataclass import FairseqDataclass +from fairseq.optim import FairseqOptimizer, register_optimizer, _build_optimizer +from fairseq.optim.lr_scheduler import FairseqLRScheduler, build_lr_scheduler +from omegaconf import II, open_dict + + +logger = logging.getLogger(__name__) + + +@dataclass +class OptimizerAndSchedulerConfig(FairseqDataclass): + optimizer: Any = None + lr_scheduler: Optional[Any] = None + lr: List = II("optimization.lr") + lr_float: Optional[ + float + ] = None # this makes it easier to sweep on learning rate with auto sweepers + + +@dataclass +class CompositeOptimizerConfig(FairseqDataclass): + groups: Dict[str, Any] = field( + default_factory=lambda: {}, + metadata={ + "help": "optimizer name -> optimizer OptimizerAndSchedulerConfig. " + "Configures a different optimizer and (optionally) lr scheduler for each parameter group" + }, + ) + + +@register_optimizer("composite", dataclass=CompositeOptimizerConfig) +class FairseqCompositeOptimizer(FairseqOptimizer): + + optimizers: Dict[str, FairseqOptimizer] = {} + lr_schedulers: Dict[str, FairseqLRScheduler] = {} + lr_scheduler: FairseqLRScheduler = None + _optimizer: torch.optim.Optimizer + + def __init__(self, cfg: CompositeOptimizerConfig, params): + super().__init__(cfg) + + assert ( + len(params) > 1 + ), "Composite optimizer only works when there are multiple parameter groups (try fp16_no_flatten_grads: true)" + + groupped_params = defaultdict(list) + for p in params: + group = getattr(p, "param_group", "default") + groupped_params[group].append(p) + + assert groupped_params.keys() == cfg.groups.keys(), ( + f"Parameter groups {groupped_params.keys()} and optimizer groups {cfg.groups.keys()} are not the same! " + "Try setting 'param_group' on your parameters in the model." + ) + + for group, group_params in groupped_params.items(): + group_cfg = cfg.groups[group] + with open_dict(group_cfg): + if group_cfg.lr_float is not None: + group_cfg.optimizer.lr = [group_cfg.lr_float] + group_cfg.lr_scheduler.lr = [group_cfg.lr_float] + else: + group_cfg.optimizer.lr = group_cfg.lr + group_cfg.lr_scheduler.lr = group_cfg.lr + self.optimizers[group] = _build_optimizer(group_cfg.optimizer, group_params) + if group_cfg.lr_scheduler is not None: + self.lr_schedulers[group] = build_lr_scheduler( + group_cfg.lr_scheduler, self.optimizers[group] + ) + + if len(self.lr_schedulers) > 0: + assert len(self.lr_schedulers) == len(self.optimizers), ( + f"Please provide an lr scheduler for each optimizer to use pass_through scheduler. " + f"Optimizers: {self.optimizers}; Lr scheds: {self.lr_schedulers}" + ) + self.lr_scheduler = CompositeLRScheduler(self.lr_schedulers) + + self._optimizer = CompositeOptimizer(self.optimizers) + + @property + def supports_groups(self): + return True + + @property + def param_groups(self): + for opt in self.optimizers.values(): + for group in opt.param_groups: + yield group + + def get_lr(self): + """Return the current learning rate.""" + k = ( + "default" + if "default" in self.optimizers + else next(iter(self.optimizers.keys())) + ) + return self.optimizers[k].param_groups[0]["lr"] + + def state_dict(self): + """Return the LR scheduler state dict.""" + return {k: s.state_dict() for k, s in self.optimizers.items()} + + def load_state_dict(self, state_dict, optimizer_overrides=None): + """Load an LR scheduler state dict.""" + for k, state in state_dict.items(): + if k not in self.optimizers: + # skip extra keys like "loss_scale" added by fp16 optimizer + continue + + overrides = ( + optimizer_overrides[k] + if isinstance(optimizer_overrides, dict) and k in optimizer_overrides + else None + ) + self.optimizers[k].load_state_dict(state, optimizer_overrides=overrides) + + +class CompositeOptimizer(torch.optim.Optimizer): + def __init__(self, optimizers: Dict[str, FairseqOptimizer]): + self.optimizers = optimizers + + @property + def supports_memory_efficient_fp16(self): + return all(o.supports_memory_efficient_fp16 for o in self.optimizers.values()) + + @property + def supports_flat_params(self): + return all(o.supports_flat_params for o in self.optimizers.values()) + + def step(self, closure=None, groups=None): + """Performs a single optimization step. + + Args: + closure (callable, optional): A closure that reevaluates the model + and returns the loss. + """ + loss = None + if closure is not None: + loss = closure() + + for k, opt in self.optimizers.items(): + if groups is None or k in groups: + opt.step() + + return loss + + def zero_grad(self): + for opt in self.optimizers.values(): + opt.zero_grad() + + +class CompositeLRScheduler(FairseqLRScheduler): + def __init__(self, lr_schedulers): + super().__init__(None, None) + + self.lr_schedulers = lr_schedulers + + def state_dict(self): + """Return the LR scheduler state dict.""" + return {k: s.state_dict() for k, s in self.lr_schedulers.items()} + + def load_state_dict(self, state_dict): + """Load an LR scheduler state dict.""" + for k, state in state_dict.items(): + self.lr_schedulers[k].load_state_dict(state) + + def step_begin_epoch(self, epoch): + """Update the learning rate at the beginning of the given epoch.""" + for s in self.lr_schedulers.values(): + s.step_begin_epoch(epoch) + + def step(self, epoch, val_loss=None): + """Update the learning rate at the end of the given epoch.""" + for s in self.lr_schedulers.values(): + s.step(epoch) + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + return {k: s.step_update(num_updates) for k, s in self.lr_schedulers.items()} diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/cpu_adam.py b/PyTorch/NLP/new-Transformer/fairseq/optim/cpu_adam.py new file mode 100644 index 00000000..b218934e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/cpu_adam.py @@ -0,0 +1,210 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import importlib +from collections.abc import Collection +from dataclasses import dataclass, field +from typing import List + +import torch +from fairseq.dataclass import FairseqDataclass +from fairseq.optim import FairseqOptimizer, register_optimizer +from omegaconf import II, DictConfig + + +try: + import deepspeed + + has_deepspeed = True +except ImportError as e: + has_deepspeed = False + + +def _get_cpu_adam(): + try: + from deepspeed.ops.op_builder import CPUAdamBuilder + + return CPUAdamBuilder().load() + except ImportError: + # fbcode + from deepspeed.ops.adam import DeepSpeedCPUAdam as ds_opt_adam + + return ds_opt_adam + + +@dataclass +class FairseqCPUAdamConfig(FairseqDataclass): + adam_betas: str = field( + default="(0.9, 0.999)", metadata={"help": "betas for Adam optimizer"} + ) + adam_eps: float = field( + default=1e-8, metadata={"help": "epsilon for Adam optimizer"} + ) + weight_decay: float = field(default=0.0, metadata={"help": "weight decay"}) + fp16_adam_stats: bool = field( + default=False, metadata={"help": "use FP16 stats (with automatic scaling)"} + ) + # TODO common vars below in parent + lr: List[float] = II("optimization.lr") + + +@register_optimizer("cpu_adam", dataclass=FairseqCPUAdamConfig) +class FairseqCPUAdam(FairseqOptimizer): + """Adam optimizer for fairseq, optimized for CPU tensors. + + Important note: this optimizer corresponds to the "AdamW" variant of + Adam in its weight decay behavior. As such, it is most closely + analogous to torch.optim.AdamW from PyTorch. + """ + + def __init__(self, cfg: DictConfig, params): + super().__init__(cfg) + self._optimizer = CPUAdam(params, **self.optimizer_config) + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + return { + "lr": self.cfg.lr[0] + if isinstance(self.cfg.lr, Collection) + else self.cfg.lr, + "betas": eval(self.cfg.adam_betas), + "eps": self.cfg.adam_eps, + "weight_decay": self.cfg.weight_decay, + "use_fp16_stats": self.cfg.fp16_adam_stats, + } + + +class CPUAdam(torch.optim.Optimizer): + + optimizer_id = 0 + + def __init__( + self, + params, + lr=1e-3, + bias_correction=True, + betas=(0.9, 0.999), + eps=1e-8, + weight_decay=0, + use_fp16_stats=False, + ): + defaults = { + "lr": lr, + "bias_correction": bias_correction, + "betas": betas, + "eps": eps, + "weight_decay": weight_decay, + } + super().__init__(params, defaults) + + self.use_fp16_stats = use_fp16_stats + self.FLOAT16_MAX = 65504.0 + + if not has_deepspeed: + raise ImportError("Please install DeepSpeed: pip install deepspeed") + + self.opt_id = CPUAdam.optimizer_id + CPUAdam.optimizer_id = CPUAdam.optimizer_id + 1 + + self.ds_opt_adam = _get_cpu_adam() + adamw_mode = True + self.ds_opt_adam.create_adam( + self.opt_id, lr, betas[0], betas[1], eps, weight_decay, adamw_mode + ) + + @property + def supports_memory_efficient_fp16(self): + return True + + @property + def supports_flat_params(self): + return True + + @torch.no_grad() + def step(self, closure=None): + loss = None + if closure is not None: + with torch.enable_grad(): + loss = closure() + + torch.cuda.synchronize() + + for group_id, group in enumerate(self.param_groups): + for param_id, p in enumerate(group["params"]): + if p.grad is None: + continue + + state = self.state[p] + if len(state) == 0: + state["step"] = 0 + dtype = torch.float16 if self.use_fp16_stats else p.data.dtype + # gradient momentums + state["exp_avg"] = torch.zeros_like( + p.data, dtype=dtype, device="cpu" + ) + # gradient variances + state["exp_avg_sq"] = torch.zeros_like( + p.data, dtype=dtype, device="cpu" + ) + if self.use_fp16_stats: + assert torch.is_floating_point(p.data) + state["exp_avg_scale"] = 1.0 + state["exp_avg_sq_scale"] = 1.0 + + exp_avg, exp_avg_sq = state["exp_avg"], state["exp_avg_sq"] + + p_data_bak = p.data # backup of the original data pointer + + p.data = p.data.to(dtype=torch.float32, device="cpu") + p.grad.data = p.grad.data.to(dtype=torch.float32, device="cpu") + + if self.use_fp16_stats: + exp_avg = exp_avg.float() * state["exp_avg_scale"] + exp_avg_sq = exp_avg_sq.float() * state["exp_avg_sq_scale"] + + state["step"] += 1 + beta1, beta2 = group["betas"] + + self.ds_opt_adam.adam_update( + self.opt_id, + state["step"], + group["lr"], + beta1, + beta2, + group["eps"], + group["weight_decay"], + group["bias_correction"], + p.data, + p.grad.data, + exp_avg, + exp_avg_sq, + ) + + if p_data_bak.data_ptr() != p.data.data_ptr(): + p_data_bak.copy_(p.data) + p.data = p_data_bak + + if self.use_fp16_stats: + + def inf_norm(t): + return torch.norm(t, float("inf")) + + # from github.com/openai/jukebox/blob/master/jukebox/utils/fp16.py + state["exp_avg_scale"], state["exp_avg_sq_scale"] = ( + 1e-8 + inf_norm(exp_avg) / self.FLOAT16_MAX, + 1e-8 + inf_norm(exp_avg_sq) / self.FLOAT16_MAX, + ) + state["exp_avg"], state["exp_avg_sq"] = ( + (exp_avg / state["exp_avg_scale"]).half(), + (exp_avg_sq / state["exp_avg_sq_scale"]).half(), + ) + + return loss diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/dynamic_loss_scaler.py b/PyTorch/NLP/new-Transformer/fairseq/optim/dynamic_loss_scaler.py new file mode 100644 index 00000000..60c47b8d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/dynamic_loss_scaler.py @@ -0,0 +1,70 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +class DynamicLossScaler(object): + def __init__( + self, + init_scale=2.0**15, + scale_factor=2.0, + scale_window=2000, + tolerance=0.0, + threshold=None, + min_loss_scale=1e-4, + ): + self.loss_scale = init_scale + self.scale_factor = scale_factor + self.scale_window = scale_window + self.tolerance = tolerance + self.threshold = threshold + self._iter = 0 + self._last_overflow_iter = -1 + self._last_rescale_iter = -1 + self._overflows_since_rescale = 0 + self.min_loss_scale = min_loss_scale + + def scale(self, outputs): + return self.loss_scale * outputs + + def update(self): + if (self._iter - self._last_overflow_iter) % self.scale_window == 0: + self.loss_scale *= self.scale_factor + self._last_rescale_iter = self._iter + self._iter += 1 + + def _decrease_loss_scale(self): + self.loss_scale /= self.scale_factor + if self.threshold is not None: + self.loss_scale = max(self.loss_scale, self.threshold) + + def check_overflow(self, grad_norm): + # detect inf and nan + if grad_norm == float("inf") or grad_norm != grad_norm: + # overflow has occured + prev_scale = self.loss_scale + iter_since_rescale = self._iter - self._last_rescale_iter + + self._last_overflow_iter = self._iter + self._overflows_since_rescale += 1 + pct_overflow = self._overflows_since_rescale / float(iter_since_rescale) + if pct_overflow >= self.tolerance: + self._decrease_loss_scale() + self._last_rescale_iter = self._iter + self._overflows_since_rescale = 0 + + if self.loss_scale <= self.min_loss_scale: + # Use FloatingPointError as an uncommon error that parent + # functions can safely catch to stop training. + self.loss_scale = prev_scale + raise FloatingPointError( + ( + "Minimum loss scale reached ({}). Your loss is probably exploding. " + "Try lowering the learning rate, using gradient clipping or " + "increasing the batch size." + ).format(self.min_loss_scale) + ) + + self._iter += 1 + raise OverflowError("setting loss scale to: " + str(self.loss_scale)) diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/fairseq_optimizer.py b/PyTorch/NLP/new-Transformer/fairseq/optim/fairseq_optimizer.py new file mode 100644 index 00000000..7e541175 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/fairseq_optimizer.py @@ -0,0 +1,179 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from fairseq import utils +from fairseq.dataclass.utils import gen_parser_from_dataclass + + +class FairseqOptimizer(object): + def __init__(self, cfg): + super().__init__() + self.cfg = cfg + + @classmethod + def add_args(cls, parser): + """Add optimizer-specific arguments to the parser.""" + dc = getattr(cls, "__dataclass", None) + if dc is not None: + gen_parser_from_dataclass(parser, dc()) + + @property + def optimizer(self): + """Return a torch.optim.optimizer.Optimizer instance.""" + if not hasattr(self, "_optimizer"): + raise NotImplementedError + if not isinstance(self._optimizer, torch.optim.Optimizer): + raise ValueError("_optimizer must be an instance of torch.optim.Optimizer") + return self._optimizer + + @optimizer.setter + def optimizer(self, optimizer): + """Reset optimizer instance.""" + if not hasattr(self, "_optimizer"): + raise NotImplementedError + if not isinstance(self._optimizer, torch.optim.Optimizer): + raise ValueError("_optimizer must be an instance of torch.optim.Optimizer") + self._optimizer = optimizer + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + raise NotImplementedError + + @property + def params(self): + """Return an iterable of the parameters held by the optimizer.""" + for param_group in self.param_groups: + for p in param_group["params"]: + yield p + + @property + def param_groups(self): + return self.optimizer.param_groups + + def __getstate__(self): + return self._optimizer.__getstate__() + + def get_lr(self): + """Return the current learning rate.""" + return self.param_groups[0]["lr"] + + def set_lr(self, lr): + """Set the learning rate.""" + for param_group in self.param_groups: + param_group["lr"] = lr + + def state_dict(self): + """Return the optimizer's state dict.""" + return self.optimizer.state_dict() + + def load_state_dict(self, state_dict, optimizer_overrides=None): + """Load an optimizer state dict. + + In general we should prefer the configuration of the existing optimizer + instance (e.g., learning rate) over that found in the state_dict. This + allows us to resume training from a checkpoint using a new set of + optimizer args. + """ + self.optimizer.load_state_dict(state_dict) + + if optimizer_overrides is not None and len(optimizer_overrides) > 0: + # override learning rate, momentum, etc. with latest values + for group in self.param_groups: + group.update(optimizer_overrides) + + def backward(self, loss): + """Computes the sum of gradients of the given tensor w.r.t. graph leaves.""" + loss.backward() + + def all_reduce_grads(self, module): + """Manually all-reduce gradients (if required).""" + if hasattr(module, "all_reduce_grads"): + module.all_reduce_grads() + + def multiply_grads(self, c): + """Multiplies grads by a constant *c*.""" + for p in self.params: + if p.grad is not None: + if torch.is_tensor(c): + c = c.to(p.grad.device) + p.grad.data.mul_(c) + + def clip_grad_norm(self, max_norm, aggregate_norm_fn=None): + """Clips gradient norm.""" + return utils.clip_grad_norm_(self.params, max_norm, aggregate_norm_fn) + + def step(self, closure=None, scale=1.0, groups=None): + """Performs a single optimization step.""" + if self.supports_step_with_scale: + if self.supports_groups: + self.optimizer.step(closure, scale=scale, groups=groups) + else: + self.optimizer.step(closure, scale=scale) + else: + if scale != 1.0: + self.multiply_grads(1.0 / scale) + if self.supports_groups: + self.optimizer.step(closure, groups=groups) + else: + self.optimizer.step(closure) + + def zero_grad(self): + """Clears the gradients of all optimized parameters.""" + for p in self.params: + p.grad = None + self.optimizer.zero_grad() + + @property + def supports_memory_efficient_fp16(self): + if hasattr(self.optimizer, "supports_memory_efficient_fp16"): + return self.optimizer.supports_memory_efficient_fp16 + return False + + @property + def supports_step_with_scale(self): + if hasattr(self.optimizer, "supports_step_with_scale"): + return self.optimizer.supports_step_with_scale + return False + + @property + def supports_groups(self): + if hasattr(self.optimizer, "supports_groups"): + return self.optimizer.supports_groups + return False + + @property + def supports_flat_params(self): + """ + Whether the optimizer supports collapsing of the model + parameters/gradients into a single contiguous Tensor. + """ + if hasattr(self.optimizer, "supports_flat_params"): + return self.optimizer.supports_flat_params + return False + + def average_params(self): + pass + + def broadcast_global_state_dict(self, state_dict): + """ + Broadcasts a global state dict to all ranks. + Useful for optimizers that shard state between ranks. + """ + if hasattr(self.optimizer, "broadcast_global_state_dict"): + return self.optimizer.broadcast_global_state_dict(state_dict) + else: + return state_dict + + +class LegacyFairseqOptimizer(FairseqOptimizer): + def __init__(self, args): + self.args = args diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/fp16_optimizer.py b/PyTorch/NLP/new-Transformer/fairseq/optim/fp16_optimizer.py new file mode 100644 index 00000000..2c4ee326 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/fp16_optimizer.py @@ -0,0 +1,553 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections import defaultdict +from itertools import chain + +import torch +from omegaconf import DictConfig + +from fairseq import optim + +from .dynamic_loss_scaler import DynamicLossScaler + + +class _FP16OptimizerMixin(object): + def __init__(self, *args, **kwargs): + # forward __init__ call to the next class in mro(method resolution order) + super().__init__(*args, **kwargs) + self._multiply_factor = 1.0 + + @property + def has_flat_params(self): + return torch.is_tensor(self.fp32_params) or ( + isinstance(self.fp32_params, dict) + and all(torch.is_tensor(t) for t in self.fp32_params.values()) + ) + + @classmethod + def build_fp32_params(cls, args, params, flatten=True): + # create FP32 copy of parameters and grads + if flatten: + is_pipeline_parallel = getattr( + args, "pipeline_model_parallel", False + ) and getattr(args, "distributed_no_spawn", False) + total_param_size = sum(p.data.numel() for p in params) + devices = [torch.cuda.current_device()] + if is_pipeline_parallel: + devices = list(set(args.pipeline_devices)) + fp32_params = {} + for device in devices: + if is_pipeline_parallel: + device_param_size = sum( + p.data.numel() for p in params if p.device.index == device + ) + device_params = [p for p in params if p.device.index == device] + else: + device_param_size = total_param_size + device_params = params + fp32_params[device] = ( + device_params[0].new(0).float().new(device_param_size) + ) + offset = 0 + for p in device_params: + numel = p.data.numel() + fp32_params[device][offset : offset + numel].copy_(p.data.view(-1)) + offset += numel + fp32_params[device] = torch.nn.Parameter(fp32_params[device]) + fp32_params[device].grad = fp32_params[device].data.new( + device_param_size + ) + return fp32_params + else: + fp32_params = [] + for p in params: + p32 = torch.nn.Parameter(p.data.float()) + if hasattr(p, "expert"): + p32.expert = True + elif hasattr(p, "base_expert"): + p32.base_expert = True + p32.grad = torch.zeros_like(p32.data) + if hasattr(p, "param_group"): + p32.param_group = p.param_group + fp32_params.append(p32) + return fp32_params + + def state_dict(self): + """Return the optimizer's state dict.""" + state_dict = self.fp32_optimizer.state_dict() + if self.scaler is not None: + state_dict["loss_scale"] = self.scaler.loss_scale + return state_dict + + def load_state_dict(self, state_dict, optimizer_overrides=None): + """Load an optimizer state dict. + + In general we should prefer the configuration of the existing optimizer + instance (e.g., learning rate) over that found in the state_dict. This + allows us to resume training from a checkpoint using a new set of + optimizer args. + """ + if "loss_scale" in state_dict and self.scaler is not None: + self.scaler.loss_scale = state_dict["loss_scale"] + self.fp32_optimizer.load_state_dict(state_dict, optimizer_overrides) + + def backward(self, loss): + """Computes the sum of gradients of the given tensor w.r.t. graph leaves. + + Compared to :func:`fairseq.optim.FairseqOptimizer.backward`, this + function additionally dynamically scales the loss to avoid gradient + underflow. + """ + if self.scaler is not None: + loss = self.scaler.scale(loss) + loss.backward() + self._needs_sync = True + + def _sync_fp16_grads_to_fp32(self): + if self._needs_sync: + # copy FP16 grads to FP32 + if self.has_flat_params: + devices = list(self.fp32_params.keys()) + device_params_dict = defaultdict(list) + for p in self.fp16_params: + if p.requires_grad: + device_params_dict[p.device.index].append(p) + for device in devices: + device_params = device_params_dict[device] + offset = 0 + for p in device_params: + grad_data = ( + p.grad.data + if p.grad is not None + else p.data.new_zeros(p.data.shape) + ) + numel = grad_data.numel() + self.fp32_params[device].grad.data[ + offset : offset + numel + ].copy_(grad_data.view(-1)) + offset += numel + else: + for p, p32 in zip(self.fp16_params, self.fp32_params): + if not p.requires_grad: + continue + if p.grad is not None: + if p32.grad is None: + p32.grad = p.grad.data.float() + else: + p32.grad.data.copy_(p.grad.data) + else: + p32.grad = torch.zeros_like(p.data, dtype=torch.float) + + self._needs_sync = False + + def _sync_fp32_params_to_fp16(self): + # copy FP32 params back into FP16 model + if self.has_flat_params: + devices = list(self.fp32_params.keys()) + device_params_dict = defaultdict(list) + for p in self.fp16_params: + device_params_dict[p.device.index].append(p) + for device in devices: + device_params = device_params_dict[device] + offset = 0 + for p in device_params: + numel = p.data.numel() + p.data.copy_( + self.fp32_params[device] + .data[offset : offset + numel] + .view_as(p.data) + ) + offset += numel + else: + for p, p32 in zip(self.fp16_params, self.fp32_params): + if not p.requires_grad: + continue + p.data.copy_(p32.data) + + def _unscale_grads(self): + self._sync_fp16_grads_to_fp32() + if ( + # Skip the multiplication if it's a no-op (i.e., if _multiply_factor + # is 1.0). At the same time, we want to avoid the device-to-host + # transfer by comparing it to 1.0. Since _multiply_factor starts as + # a Python float, we roughly assume that if it's a tensor then it's + # probably not =1.0 anymore and we do the multiplication. Otherwise + # we can safely check the value without a D2H transfer. + torch.is_tensor(self._multiply_factor) + or self._multiply_factor != 1.0 + ): + self.fp32_optimizer.multiply_grads(self._multiply_factor) + self._multiply_factor = 1.0 + + def multiply_grads(self, c): + """Multiplies grads by a constant ``c``.""" + self._multiply_factor *= c + + def clip_grad_norm(self, max_norm, aggregate_norm_fn=None): + """Clips gradient norm and updates dynamic loss scaler.""" + self._sync_fp16_grads_to_fp32() + + grad_norm = self._multiply_factor * self.fp32_optimizer.clip_grad_norm( + 0, aggregate_norm_fn + ) + + if self.scaler is not None: + if grad_norm > max_norm > 0.0: + self._multiply_factor *= max_norm / grad_norm + + self.scaler.check_overflow(grad_norm) + elif max_norm > 0.0: + clip_coef = (max_norm / (grad_norm + 1e-6)).clamp_(max=1) + self._multiply_factor *= clip_coef + + return grad_norm + + def step(self, closure=None, groups=None): + """Performs a single optimization step.""" + self._sync_fp16_grads_to_fp32() + + if getattr(self, "supports_step_with_scale", False): + self.fp32_optimizer.step( + closure, scale=(1.0 / self._multiply_factor), groups=groups + ) + else: + self._unscale_grads() + self.fp32_optimizer.step(closure, groups=groups) + + if self.scaler is not None: + self.scaler.update() + + self._sync_fp32_params_to_fp16() + + def zero_grad(self): + """Clears the gradients of all optimized parameters.""" + for p in self.fp16_params: + p.grad = None + if self.has_flat_params: + if torch.is_tensor(self.fp32_params): + self.fp32_params.grad.zero_() + elif isinstance(self.fp32_params, dict): + for fp32_params in self.fp32_params.values(): + fp32_params.grad.zero_() + else: + raise RuntimeError("self.fp32_params must be a tensor or dict") + else: + for p32 in self.fp32_params: + if p32.grad is not None: + p32.grad.zero_() + self._needs_sync = False + + if self.scaler is not None: + self._multiply_factor = 1.0 / float(self.scaler.loss_scale) + + +class FP16Optimizer(_FP16OptimizerMixin, optim.FairseqOptimizer): + """ + Wrap an *optimizer* to support FP16 (mixed precision) training. + """ + + def __init__(self, cfg: DictConfig, params, fp32_optimizer, fp32_params, **kwargs): + super().__init__(cfg.optimizer) + self.fp16_params = params + self.fp32_optimizer = fp32_optimizer + self.fp32_params = fp32_params + + if getattr(cfg.common, "fp16_scale_window", None) is None: + if len(cfg.optimization.update_freq) > 1: + raise ValueError( + "--fp16-scale-window must be given explicitly when using a " + "custom --update-freq schedule" + ) + data_parallel_size = int( + cfg.distributed_training.distributed_world_size + / cfg.common.model_parallel_size + ) + scale_window = int( + 2**14 / data_parallel_size / cfg.optimization.update_freq[0] + ) + else: + scale_window = cfg.common.fp16_scale_window + + if not getattr(cfg.common, "bf16", False): + self.scaler = DynamicLossScaler( + init_scale=cfg.common.fp16_init_scale, + scale_window=scale_window, + tolerance=cfg.common.fp16_scale_tolerance, + threshold=cfg.common.threshold_loss_scale, + min_loss_scale=cfg.common.min_loss_scale, + ) + else: + # disable loss scaling for bfloat16 + self.scaler = None + + @classmethod + def build_optimizer(cls, cfg: DictConfig, params, **kwargs): + """ + Args: + cfg (omegaconf.DictConfig): fairseq args + params (iterable): iterable of parameters to optimize + """ + flatten = not getattr(cfg.common, "fp16_no_flatten_grads", False) + if getattr(cfg.common, "bf16", False): + flatten = False # mixed precision is faster on TPUs without flat grads + fp32_params = cls.build_fp32_params(cfg.optimizer, params, flatten=flatten) + if flatten: + fp32_optimizer = optim.build_optimizer(cfg.optimizer, [fp32_params]) + else: + fp32_optimizer = optim.build_optimizer(cfg.optimizer, fp32_params) + if flatten and not fp32_optimizer.supports_flat_params: + raise RuntimeError( + f"chosen optimizer {fp32_optimizer.__class__.__name__} does not support flat params, please set --fp16-no-flatten-grads" + ) + return cls(cfg, params, fp32_optimizer, fp32_params, **kwargs) + + @property + def optimizer(self): + return self.fp32_optimizer.optimizer + + @optimizer.setter + def optimizer(self, optimizer): + self.fp32_optimizer.optimizer = optimizer + + @property + def lr_scheduler(self): + return getattr(self.fp32_optimizer, "lr_scheduler", None) + + @property + def optimizer_config(self): + return self.fp32_optimizer.optimizer_config + + def get_lr(self): + return self.fp32_optimizer.get_lr() + + def set_lr(self, lr): + self.fp32_optimizer.set_lr(lr) + + def all_reduce_grads(self, module): + self.fp32_optimizer.all_reduce_grads(module) + + @property + def supports_flat_params(self): + return self.fp32_optimizer.supports_flat_params + + +class _MemoryEfficientFP16OptimizerMixin(object): + def __init__(self, *args, **kwargs): + # forward __init__ call to the next class in MRO (method resolution order) + super().__init__(*args, **kwargs) + self._multiply_factor = 1.0 + + @property + def has_flat_params(self): + return False + + def state_dict(self): + """Return the optimizer's state dict.""" + state_dict = self.wrapped_optimizer.state_dict() + if self.scaler is not None: + state_dict["loss_scale"] = self.scaler.loss_scale + return state_dict + + def load_state_dict(self, state_dict, optimizer_overrides=None): + """Load an optimizer state dict. + + In general we should prefer the configuration of the existing optimizer + instance (e.g., learning rate) over that found in the state_dict. This + allows us to resume training from a checkpoint using a new set of + optimizer args. + """ + if "loss_scale" in state_dict and self.scaler is not None: + self.scaler.loss_scale = state_dict["loss_scale"] + + self.wrapped_optimizer.load_state_dict(state_dict, optimizer_overrides) + + # Hack: PyTorch automatically casts the optimizer state to match the + # type of the current parameters. But with --memory-efficient-fp16 the + # params are FP16 while the optimizer state is FP32 and we don't want + # to cast. A workaround is to manually copy back the original state + # after the optimizer has been loaded. + if not getattr(self.optimizer, "disable_mem_eff_fp16_loading_hack", False): + groups = self.optimizer.param_groups + saved_groups = state_dict["param_groups"] + id_map = { + old_id: p + for old_id, p in zip( + chain(*(g["params"] for g in saved_groups)), + chain(*(g["params"] for g in groups)), + ) + } + for k, v in state_dict["state"].items(): + if k in id_map: + param = id_map[k] + self.optimizer.state[param] = v + + def backward(self, loss): + """Computes the sum of gradients of the given tensor w.r.t. graph leaves. + + Compared to :func:`fairseq.optim.FairseqOptimizer.backward`, this + function additionally dynamically scales the loss to avoid gradient + underflow. + """ + if self.scaler is not None: + loss = self.scaler.scale(loss) + loss.backward() + + def _unscale_grads(self): + if ( + # Skip the multiplication if it's a no-op (i.e., if _multiply_factor + # is 1.0). At the same time, we want to avoid the device-to-host + # transfer by comparing it to 1.0. Since _multiply_factor starts as + # a Python float, we roughly assume that if it's a tensor then it's + # probably not =1.0 anymore and we do the multiplication. Otherwise + # we can safely check the value without a D2H transfer. + torch.is_tensor(self._multiply_factor) + or self._multiply_factor != 1.0 + ): + self.wrapped_optimizer.multiply_grads(self._multiply_factor) + self._multiply_factor = 1.0 + + def multiply_grads(self, c): + """Multiplies grads by a constant *c*.""" + self._multiply_factor *= c + + def clip_grad_norm(self, max_norm, aggregate_norm_fn=None): + """Clips gradient norm and updates dynamic loss scaler.""" + max_norm = float(max_norm) + grad_norm = self._multiply_factor * self.wrapped_optimizer.clip_grad_norm( + 0, aggregate_norm_fn + ) + + if self.scaler is not None: + grad_norm_cpu = float(grad_norm) + if grad_norm_cpu > max_norm > 0.0: + self._multiply_factor *= max_norm / grad_norm_cpu + + # detect overflow and adjust loss scale + self.scaler.check_overflow(grad_norm_cpu) + elif max_norm > 0.0: + clip_coef = (max_norm / (grad_norm + 1e-6)).clamp_(max=1) + self._multiply_factor *= clip_coef + + return grad_norm + + def step(self, closure=None, groups=None): + """Performs a single optimization step.""" + if getattr(self, "supports_step_with_scale", False): + # NOTE(msb) optimizer divides by scale factor + self.wrapped_optimizer.step( + closure, scale=(1.0 / self._multiply_factor), groups=groups + ) + else: + self._unscale_grads() + self.wrapped_optimizer.step(closure, groups=groups) + + if self.scaler is not None: + self.scaler.update() + + def zero_grad(self): + """Clears the gradients of all optimized parameters.""" + self.wrapped_optimizer.zero_grad() + if self.scaler is not None: + self._multiply_factor = 1.0 / float(self.scaler.loss_scale) + else: + self._multiply_factor = 1.0 + + @property + def supports_flat_params(self): + return self.wrapped_optimizer.supports_flat_params + + +class MemoryEfficientFP16Optimizer( + _MemoryEfficientFP16OptimizerMixin, optim.FairseqOptimizer +): + """ + Wrap an *optimizer* to support FP16 (mixed precision) training. + + Compared to :class:`fairseq.optim.FP16Optimizer`, this version does not + maintain an FP32 copy of the model. We instead expect the optimizer to + convert the gradients to FP32 internally and sync the results back to the + FP16 model params. This significantly reduces memory usage but slightly + increases the time spent in the optimizer. + + Since this wrapper depends on specific functionality in the wrapped + optimizer (i.e., on-the-fly conversion of grads to FP32), only certain + optimizers can be wrapped. This is determined by the + *supports_memory_efficient_fp16* property. + """ + + def __init__( + self, cfg: DictConfig, params, optimizer, allow_unsupported=False, **kwargs + ): + if not allow_unsupported and not optimizer.supports_memory_efficient_fp16: + raise ValueError( + "Unsupported optimizer: {}".format(optimizer.__class__.__name__) + ) + + super().__init__(getattr(cfg, "optimizer", None)) + self.wrapped_optimizer = optimizer + + if getattr(cfg.common, "fp16_scale_window", None) is None: + if len(cfg.optimization.update_freq) > 1: + raise ValueError( + "--fp16-scale-window must be given explicitly when using a " + "custom --update-freq schedule" + ) + data_parallel_size = int( + cfg.distributed_training.distributed_world_size + / cfg.common.model_parallel_size + ) + scale_window = int( + 2**14 / data_parallel_size / cfg.optimization.update_freq[0] + ) + else: + scale_window = cfg.common.fp16_scale_window + + if not getattr(cfg.common, "bf16", False): + self.scaler = DynamicLossScaler( + init_scale=cfg.common.fp16_init_scale, + scale_window=scale_window, + tolerance=cfg.common.fp16_scale_tolerance, + threshold=cfg.common.threshold_loss_scale, + min_loss_scale=cfg.common.min_loss_scale, + ) + else: + # disable loss scaling for bfloat16 + self.scaler = None + + @classmethod + def build_optimizer(cls, cfg: DictConfig, params, **kwargs): + """ + Args: + args (argparse.Namespace): fairseq args + params (iterable): iterable of parameters to optimize + """ + fp16_optimizer = optim.build_optimizer(cfg.optimizer, params) + return cls(cfg, params, fp16_optimizer, **kwargs) + + @property + def optimizer(self): + return self.wrapped_optimizer.optimizer + + @optimizer.setter + def optimizer(self, optimizer): + self.wrapped_optimizer.optimizer = optimizer + + @property + def optimizer_config(self): + return self.wrapped_optimizer.optimizer_config + + @property + def lr_scheduler(self): + return getattr(self.wrapped_optimizer, "lr_scheduler", None) + + def get_lr(self): + return self.wrapped_optimizer.get_lr() + + def set_lr(self, lr): + self.wrapped_optimizer.set_lr(lr) + + def all_reduce_grads(self, module): + self.wrapped_optimizer.all_reduce_grads(module) diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/fused_adam.py b/PyTorch/NLP/new-Transformer/fairseq/optim/fused_adam.py new file mode 100644 index 00000000..1290ecfd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/fused_adam.py @@ -0,0 +1,386 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import types + +import torch + + +def get_fused_adam_class(): + """ + Look for the FusedAdam optimizer from apex. We first try to load the + "contrib" interface, which is a bit faster than the main interface, + but is technically deprecated. + """ + try: + # The "deprecated" interface in recent versions of apex is a bit + # faster than the main interface, since we don't use the apex + # optimizer. This can be installed by passing the + # `--deprecated_fused_adam` option when building apex. + global fused_adam_cuda + import importlib + + fused_adam_cuda = importlib.import_module("fused_adam_cuda") + return FusedAdamV1 + except ImportError: + try: + # fallback to the newer interface + from apex.multi_tensor_apply import multi_tensor_applier + from apex.optimizers import FusedAdam as _FusedAdam # noqa + + if multi_tensor_applier.available: + return FusedAdamV2 + except ImportError: + pass + return None + + +class FusedAdamV1(torch.optim.Optimizer): + """ + Implements Adam algorithm. Currently GPU-only. Requires Apex to be installed via + ``python setup.py install --cuda_ext --cpp_ext``. + + It has been proposed in `Adam: A Method for Stochastic Optimization`_. + + Compared to the original version in Apex, the fairseq version casts grads + and params to FP32 internally to support ``--memory-efficient-fp16``. + + Args: + params (iterable): iterable of parameters to optimize or dicts defining + parameter groups. + lr (float, optional): learning rate. (default: 1e-3) + betas (Tuple[float, float], optional): coefficients used for computing + running averages of gradient and its square. (default: (0.9, 0.999)) + eps (float, optional): term added to the denominator to improve + numerical stability. (default: 1e-8) + weight_decay (float, optional): weight decay (L2 penalty) (default: 0) + amsgrad (boolean, optional): whether to use the AMSGrad variant of this + algorithm from the paper `On the Convergence of Adam and Beyond`_ + (default: False) NOT SUPPORTED in FusedAdam! + eps_inside_sqrt (boolean, optional): in the 'update parameters' step, + adds eps to the bias-corrected second moment estimate before + evaluating square root instead of adding it to the square root of + second moment estimate as in the original paper. (default: False) + .. _Adam: A Method for Stochastic Optimization: + https://arxiv.org/abs/1412.6980 + .. _On the Convergence of Adam and Beyond: + https://openreview.net/forum?id=ryQu7f-RZ + """ + + def __init__( + self, + params, + lr=1e-3, + bias_correction=True, + betas=(0.9, 0.999), + eps=1e-8, + eps_inside_sqrt=False, + weight_decay=0.0, + max_grad_norm=0.0, + amsgrad=False, + use_fp16_stats=False, + ): + global fused_adam_cuda + import importlib + + fused_adam_cuda = importlib.import_module("fused_adam_cuda") + + if amsgrad: + raise RuntimeError("FusedAdam does not support the AMSGrad variant.") + defaults = { + "lr": lr, + "bias_correction": bias_correction, + "betas": betas, + "eps": eps, + "weight_decay": weight_decay, + "max_grad_norm": max_grad_norm, + } + super().__init__(params, defaults) + self.eps_mode = 0 if eps_inside_sqrt else 1 + + self.use_fp16_stats = use_fp16_stats + self.FLOAT16_MAX = 65504.0 + + @property + def supports_memory_efficient_fp16(self): + return True + + @property + def supports_flat_params(self): + return True + + @property + def supports_step_with_scale(self): + return True + + def step(self, closure=None, grads=None, scale=1.0, grad_norms=None): + """Performs a single optimization step. + Args: + closure (callable, optional): A closure that reevaluates the model + and returns the loss. + grads (list of tensors, optional): weight gradient to use for the + optimizer update. If gradients have type torch.half, parameters + are expected to be in type torch.float. (default: None) + output params (list of tensors, optional): A reduced precision copy + of the updated weights written out in addition to the regular + updated weights. Have to be of same type as gradients. (default: None) + scale (float, optional): factor to divide gradient tensor values + by before applying to weights. (default: 1) + """ + loss = None + if closure is not None: + loss = closure() + + if grads is None: + grads_group = [None] * len(self.param_groups) + # backward compatibility + # assuming a list/generator of parameter means single group + elif isinstance(grads, types.GeneratorType): + grads_group = [grads] + elif type(grads[0]) != list: + grads_group = [grads] + else: + grads_group = grads + + if grad_norms is None: + grad_norms = [None] * len(self.param_groups) + + for group, grads_this_group, grad_norm in zip( + self.param_groups, grads_group, grad_norms + ): + if grads_this_group is None: + grads_this_group = [None] * len(group["params"]) + + # compute combined scale factor for this group + combined_scale = scale + if group.get("max_grad_norm", 0) > 0: + # norm is in fact norm*scale + clip = ((grad_norm / scale) + 1e-6) / group["max_grad_norm"] + if clip > 1: + combined_scale = clip * scale + + bias_correction = 1 if group.get("bias_correction", 1) else 0 + + for p, grad in zip(group["params"], grads_this_group): + # note: p.grad should not ever be set for correct + # operation of mixed precision optimizer that sometimes + # sends None gradients + if p.grad is None and grad is None: + continue + if grad is None: + grad = p.grad.data + if grad.is_sparse: + raise RuntimeError( + "FusedAdam does not support sparse gradients, " + "please consider SparseAdam instead" + ) + + if p.device.type == "cpu": + p_data_fp32 = p.data.cuda(non_blocking=True).float() + out_p = torch.tensor([], dtype=torch.float) + else: + p_data_fp32 = p.data.float() + out_p = p.data + + state = self.state[p] + + # State initialization + dtype = torch.float16 if self.use_fp16_stats else p_data_fp32.dtype + if len(state) == 0: + state["step"] = 0 + # Exponential moving average of gradient values + state["exp_avg"] = torch.zeros_like(p_data_fp32, dtype=dtype) + # Exponential moving average of squared gradient values + state["exp_avg_sq"] = torch.zeros_like(p_data_fp32, dtype=dtype) + if self.use_fp16_stats: + state["exp_avg_scale"] = 1.0 + state["exp_avg_sq_scale"] = 1.0 + else: + device = p_data_fp32.device + state["exp_avg"] = state["exp_avg"].to(device, dtype) + state["exp_avg_sq"] = state["exp_avg_sq"].to(device, dtype) + + exp_avg = state["exp_avg"] + exp_avg_sq = state["exp_avg_sq"] + if self.use_fp16_stats: + assert exp_avg.dtype == torch.float16 + exp_avg = exp_avg.float() * state["exp_avg_scale"] + exp_avg_sq = exp_avg_sq.float() * state["exp_avg_sq_scale"] + beta1, beta2 = group["betas"] + + state["step"] += 1 + + with torch.cuda.device(p_data_fp32.device): + fused_adam_cuda.adam( + p_data_fp32, + out_p, + exp_avg, + exp_avg_sq, + grad, + group["lr"], + beta1, + beta2, + group["eps"], + combined_scale, + state["step"], + self.eps_mode, + bias_correction, + group["weight_decay"], + ) + + if p.device.type == "cpu": + p.data.copy_(p_data_fp32, non_blocking=True) + + if self.use_fp16_stats: + + def inf_norm(t): + return torch.norm(t, float("inf")) + + # from github.com/openai/jukebox/blob/master/jukebox/utils/fp16.py + state["exp_avg_scale"], state["exp_avg_sq_scale"] = ( + 1e-8 + inf_norm(exp_avg) / self.FLOAT16_MAX, + 1e-8 + inf_norm(exp_avg_sq) / self.FLOAT16_MAX, + ) + state["exp_avg"], state["exp_avg_sq"] = ( + (exp_avg / state["exp_avg_scale"]).half(), + (exp_avg_sq / state["exp_avg_sq_scale"]).half(), + ) + + return loss + + +try: + from apex.multi_tensor_apply import multi_tensor_applier + from apex.optimizers import FusedAdam + + class FusedAdamV2(FusedAdam): + """ + Compared to the original version in Apex, the fairseq version casts grads + and params to FP32 internally to support ``--memory-efficient-fp16``. + """ + + def __init__(self, *args, use_fp16_stats=False, **kwargs): + if use_fp16_stats: + raise NotImplementedError( + "--fp16-adam-stats is only supported with FusedAdamV1" + ) + super().__init__(*args, **kwargs) + if not hasattr(self, "multi_tensor_adam"): + raise Exception( + "Apex installation is outdated. Please install an updated version of apex." + ) + + @property + def supports_memory_efficient_fp16(self): + return True + + @property + def supports_flat_params(self): + return True + + def step( + self, + closure=None, + grads=None, + output_params=None, + scale=None, + grad_norms=None, + ): + """Performs a single optimization step.""" + loss = None + if closure is not None: + loss = closure() + + for group in self.param_groups: + bias_correction = 1 if group["bias_correction"] else 0 + beta1, beta2 = group["betas"] + + # assume same step across group now to simplify things + # per parameter step can be easily support by making it tensor, or pass list into kernel + if "step" in group: + group["step"] += 1 + else: + group["step"] = 1 + + # create lists for multi-tensor apply + g_16, p_16, orig_p_16, m_16, v_16 = [], [], [], [], [] + g_32, p_32, m_32, v_32 = [], [], [], [] + + for p in group["params"]: + if p.grad is None: + continue + if p.grad.data.is_sparse: + raise RuntimeError( + "FusedAdam does not support sparse gradients, " + "please consider SparseAdam instead" + ) + + state = self.state[p] + # State initialization + if len(state) == 0: + # Exponential moving average of gradient values + state["exp_avg"] = torch.zeros_like(p.data, dtype=torch.float) + # Exponential moving average of squared gradient values + state["exp_avg_sq"] = torch.zeros_like( + p.data, dtype=torch.float + ) + else: + state["exp_avg"] = state["exp_avg"].to( + device=p.data.device, dtype=torch.float + ) + state["exp_avg_sq"] = state["exp_avg_sq"].to( + device=p.data.device, dtype=torch.float + ) + + if p.dtype == torch.float16: + g_16.append(p.grad.data.float()) + p_16.append(p.data.float()) + orig_p_16.append(p.data) + m_16.append(state["exp_avg"]) + v_16.append(state["exp_avg_sq"]) + elif p.dtype == torch.float32: + g_32.append(p.grad.data) + p_32.append(p.data) + m_32.append(state["exp_avg"]) + v_32.append(state["exp_avg_sq"]) + else: + raise RuntimeError("FusedAdam only support fp16 and fp32.") + + with torch.cuda.device(p.device): + if len(g_16) > 0: + multi_tensor_applier( + self.multi_tensor_adam, + self._dummy_overflow_buf, + [g_16, p_16, m_16, v_16], + group["lr"], + beta1, + beta2, + group["eps"], + group["step"], + self.adam_w_mode, + bias_correction, + group["weight_decay"], + ) + for orig_p, p in zip(orig_p_16, p_16): + orig_p.copy_(p.data) + if len(g_32) > 0: + multi_tensor_applier( + self.multi_tensor_adam, + self._dummy_overflow_buf, + [g_32, p_32, m_32, v_32], + group["lr"], + beta1, + beta2, + group["eps"], + group["step"], + self.adam_w_mode, + bias_correction, + group["weight_decay"], + ) + + return loss + +except ImportError: + pass diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/fused_lamb.py b/PyTorch/NLP/new-Transformer/fairseq/optim/fused_lamb.py new file mode 100644 index 00000000..f4f2bdb0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/fused_lamb.py @@ -0,0 +1,51 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from fairseq.optim import LegacyFairseqOptimizer, register_optimizer + + +@register_optimizer("lamb") +class FairseqLAMB(LegacyFairseqOptimizer): + """LAMB optimizer.""" + + def __init__(self, args, params): + super().__init__(args) + try: + from apex.optimizers import FusedLAMB + + self._optimizer = FusedLAMB(params, **self.optimizer_config) + except ImportError: + raise ImportError("Please install apex to use LAMB optimizer") + + @staticmethod + def add_args(parser): + """Add optimizer-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--lamb-betas', default='(0.9, 0.999)', metavar='B', + help='betas for LAMB optimizer') + parser.add_argument('--lamb-eps', type=float, default=1e-8, metavar='D', + help='epsilon for LAMB optimizer') + parser.add_argument('--weight-decay', '--wd', default=0.0, type=float, metavar='WD', + help='weight decay') + # fmt: on + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + return { + "lr": self.args.lr[0], + "betas": eval(self.args.lamb_betas), + "eps": self.args.lamb_eps, + "weight_decay": self.args.weight_decay, + } + + @property + def supports_flat_params(self): + return False diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/__init__.py new file mode 100644 index 00000000..5b3dbc02 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/__init__.py @@ -0,0 +1,36 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +import importlib +import os + +from fairseq import registry +from fairseq.optim.lr_scheduler.fairseq_lr_scheduler import ( # noqa + FairseqLRScheduler, + LegacyFairseqLRScheduler, +) +from omegaconf import DictConfig + + +( + build_lr_scheduler_, + register_lr_scheduler, + LR_SCHEDULER_REGISTRY, + LR_SCHEDULER_DATACLASS_REGISTRY, +) = registry.setup_registry( + "--lr-scheduler", base_class=FairseqLRScheduler, default="fixed" +) + + +def build_lr_scheduler(cfg: DictConfig, optimizer): + return build_lr_scheduler_(cfg, optimizer) + + +# automatically import any Python files in the optim/lr_scheduler/ directory +for file in sorted(os.listdir(os.path.dirname(__file__))): + if file.endswith(".py") and not file.startswith("_"): + file_name = file[: file.find(".py")] + importlib.import_module("fairseq.optim.lr_scheduler." + file_name) diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/cosine_lr_scheduler.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/cosine_lr_scheduler.py new file mode 100644 index 00000000..d0114349 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/cosine_lr_scheduler.py @@ -0,0 +1,147 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from collections.abc import Collection +from dataclasses import dataclass, field +from typing import List + +from omegaconf import II + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class CosineLRScheduleConfig(FairseqDataclass): + warmup_updates: int = field( + default=0, + metadata={"help": "warmup the learning rate linearly for the first N updates"}, + ) + warmup_init_lr: float = field( + default=-1, + metadata={ + "help": "initial learning rate during warmup phase; default is cfg.lr" + }, + ) + lr: List[float] = field( + default=II("optimization.lr"), + metadata={"help": "max learning rate, must be more than cfg.min_lr"}, + ) + min_lr: float = field(default=0.0, metadata={"help": "min learning rate"}) + t_mult: float = field( + default=1.0, metadata={"help": "factor to grow the length of each period"} + ) + lr_period_updates: float = field( + default=-1, metadata={"help": "initial number of updates per period"} + ) + lr_shrink: float = field( + default=0.1, metadata={"help": "shrink factor for annealing"} + ) + # This is not required, but is for convenience in inferring lr_period_updates + max_update: int = II("optimization.max_update") + + +@register_lr_scheduler("cosine", dataclass=CosineLRScheduleConfig) +class CosineLRSchedule(FairseqLRScheduler): + """Assign LR based on a cyclical schedule that follows the cosine function. + + See https://arxiv.org/pdf/1608.03983.pdf for details. + + We also support a warmup phase where we linearly increase the learning rate + from some initial learning rate (``--warmup-init-lr``) until the configured + max learning rate (``--lr``). + + During warmup:: + + lrs = torch.linspace(cfg.warmup_init_lr, cfg.lr, cfg.warmup_updates) + lr = lrs[update_num] + + After warmup:: + + lr = cfg.min_lr + 0.5*(cfg.lr - cfg.min_lr)*(1 + cos(t_curr / t_i)) + + where ``t_curr`` is current percentage of updates within the current period + range and ``t_i`` is the current period range, which is scaled by ``t_mul`` + after every iteration. + """ + + def __init__(self, cfg: CosineLRScheduleConfig, fairseq_optimizer): + super().__init__(cfg, fairseq_optimizer) + if isinstance(cfg.lr, Collection) and len(cfg.lr) > 1: + raise ValueError( + "Cannot use a fixed learning rate schedule with cosine." + f" Consider --lr-scheduler=fixed instead. ({cfg.lr})" + ) + + self.max_lr = cfg.lr[0] if isinstance(cfg.lr, Collection) else cfg.lr + assert ( + self.max_lr > cfg.min_lr + ), f"max_lr (={cfg.lr}) must be more than min_lr (={cfg.min_lr})" + + warmup_end_lr = self.max_lr + if cfg.warmup_init_lr < 0: + cfg.warmup_init_lr = cfg.min_lr + + self.t_mult = cfg.t_mult + self.period = cfg.lr_period_updates + + if self.period <= 0: + assert ( + cfg.max_update > 0 + ), "Either --max_update or --lr-period-updates must be set" + self.period = cfg.max_update - cfg.warmup_updates + + if cfg.warmup_updates > 0: + # linearly warmup for the first cfg.warmup_updates + self.lr_step = (warmup_end_lr - cfg.warmup_init_lr) / cfg.warmup_updates + else: + self.lr_step = 1 + + self.warmup_updates = cfg.warmup_updates + self.lr_shrink = cfg.lr_shrink + + # initial learning rate + self.lr = cfg.warmup_init_lr + self.optimizer.set_lr(self.lr) + + def step(self, epoch, val_loss=None): + """Update the learning rate at the end of the given epoch.""" + super().step(epoch, val_loss) + # we don't change the learning rate at epoch boundaries + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + if num_updates < self.cfg.warmup_updates: + self.lr = self.cfg.warmup_init_lr + num_updates * self.lr_step + else: + curr_updates = num_updates - self.cfg.warmup_updates + if self.t_mult != 1: + i = math.floor( + math.log( + 1 - curr_updates / self.period * (1 - self.t_mult), self.t_mult + ) + ) + t_i = self.t_mult**i * self.period + t_curr = ( + curr_updates + - (1 - self.t_mult**i) / (1 - self.t_mult) * self.period + ) + else: + i = math.floor(curr_updates / self.period) + t_i = self.period + t_curr = curr_updates - (self.period * i) + + lr_shrink = self.lr_shrink**i + min_lr = self.cfg.min_lr * lr_shrink + max_lr = self.max_lr * lr_shrink + + self.lr = min_lr + 0.5 * (max_lr - min_lr) * ( + 1 + math.cos(math.pi * t_curr / t_i) + ) + + self.optimizer.set_lr(self.lr) + return self.lr diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/fairseq_lr_scheduler.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/fairseq_lr_scheduler.py new file mode 100644 index 00000000..6c12fa56 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/fairseq_lr_scheduler.py @@ -0,0 +1,59 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from argparse import Namespace + +from fairseq.dataclass.utils import gen_parser_from_dataclass +from fairseq.optim import FairseqOptimizer + + +class FairseqLRScheduler(object): + def __init__(self, cfg, optimizer): + super().__init__() + if optimizer is not None and not isinstance(optimizer, FairseqOptimizer): + raise ValueError("optimizer must be an instance of FairseqOptimizer") + self.cfg = cfg + self.optimizer = optimizer + self.best = None + + @classmethod + def add_args(cls, parser): + """Add arguments to the parser for this LR scheduler.""" + dc = getattr(cls, "__dataclass", None) + if dc is not None: + gen_parser_from_dataclass(parser, dc()) + + def state_dict(self): + """Return the LR scheduler state dict.""" + return {"best": self.best} + + def load_state_dict(self, state_dict): + """Load an LR scheduler state dict.""" + self.best = state_dict["best"] + + def step_begin_epoch(self, epoch): + """Update the learning rate at the beginning of the given epoch.""" + pass + + def step(self, epoch, val_loss=None): + """Update the learning rate at the end of the given epoch.""" + if val_loss is not None: + if self.best is None: + self.best = val_loss + else: + self.best = min(self.best, val_loss) + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + return self.optimizer.get_lr() + + +class LegacyFairseqLRScheduler(FairseqLRScheduler): + def __init__(self, args: Namespace, optimizer): + if not isinstance(optimizer, FairseqOptimizer): + raise ValueError("optimizer must be an instance of FairseqOptimizer") + self.args = args + self.optimizer = optimizer + self.best = None diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/fixed_schedule.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/fixed_schedule.py new file mode 100644 index 00000000..d0e7e14b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/fixed_schedule.py @@ -0,0 +1,76 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +from typing import Optional, List +from omegaconf import II + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class FixedLRScheduleConfig(FairseqDataclass): + force_anneal: Optional[int] = field( + default=None, + metadata={"help": "force annealing at specified epoch"}, + ) + lr_shrink: float = field( + default=0.1, + metadata={"help": "shrink factor for annealing, lr_new = (lr * lr_shrink)"}, + ) + warmup_updates: int = field( + default=0, + metadata={"help": "warmup the learning rate linearly for the first N updates"}, + ) + lr: List[float] = II("optimization.lr") + + +@register_lr_scheduler("fixed", dataclass=FixedLRScheduleConfig) +class FixedLRSchedule(FairseqLRScheduler): + """Decay the LR on a fixed schedule.""" + + def __init__(self, cfg: FixedLRScheduleConfig, optimizer): + super().__init__(cfg, optimizer) + + self.lr = cfg.lr[0] + if cfg.warmup_updates > 0: + self.warmup_factor = 1.0 / cfg.warmup_updates + else: + self.warmup_factor = 1 + + def state_dict(self): + return {"lr": self.lr} + + def load_state_dict(self, state_dict): + if "lr" in state_dict: + self.lr = state_dict["lr"] + + def get_next_lr(self, epoch): + lrs = self.cfg.lr + if self.cfg.force_anneal is None or epoch < self.cfg.force_anneal: + # use fixed LR schedule + next_lr = lrs[min(epoch - 1, len(lrs) - 1)] + else: + # annneal based on lr_shrink + next_lr = lrs[-1] * self.cfg.lr_shrink ** ( + epoch + 1 - self.cfg.force_anneal + ) + return next_lr + + def step_begin_epoch(self, epoch): + """Update the learning rate at the beginning of the given epoch.""" + self.lr = self.get_next_lr(epoch) + self.optimizer.set_lr(self.warmup_factor * self.lr) + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + if self.cfg.warmup_updates > 0 and num_updates < self.cfg.warmup_updates: + self.warmup_factor = (num_updates + 1) / float(self.cfg.warmup_updates) + self.optimizer.set_lr(self.warmup_factor * self.lr) + else: + self.optimizer.set_lr(self.lr) + return self.optimizer.get_lr() diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/inverse_square_root_schedule.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/inverse_square_root_schedule.py new file mode 100644 index 00000000..987c905a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/inverse_square_root_schedule.py @@ -0,0 +1,85 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections.abc import Collection +from dataclasses import dataclass, field +from typing import List + +from omegaconf import II + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class InverseSquareRootLRScheduleConfig(FairseqDataclass): + warmup_updates: int = field( + default=4000, + metadata={"help": "warmup the learning rate linearly for the first N updates"}, + ) + warmup_init_lr: float = field( + default=-1, + metadata={ + "help": "initial learning rate during warmup phase; default is cfg.lr" + }, + ) + lr: List[float] = II("optimization.lr") + + +@register_lr_scheduler("inverse_sqrt", dataclass=InverseSquareRootLRScheduleConfig) +class InverseSquareRootSchedule(FairseqLRScheduler): + """Decay the LR based on the inverse square root of the update number. + + We also support a warmup phase where we linearly increase the learning rate + from some initial learning rate (``--warmup-init-lr``) until the configured + learning rate (``--lr``). Thereafter we decay proportional to the number of + updates, with a decay factor set to align with the configured learning rate. + + During warmup:: + + lrs = torch.linspace(cfg.warmup_init_lr, cfg.lr, cfg.warmup_updates) + lr = lrs[update_num] + + After warmup:: + + decay_factor = cfg.lr * sqrt(cfg.warmup_updates) + lr = decay_factor / sqrt(update_num) + """ + + def __init__(self, cfg: InverseSquareRootLRScheduleConfig, optimizer): + super().__init__(cfg, optimizer) + if isinstance(cfg.lr, Collection) and len(cfg.lr) > 1: + raise ValueError( + "Cannot use a fixed learning rate schedule with inverse_sqrt." + " Consider --lr-scheduler=fixed instead." + ) + warmup_end_lr = cfg.lr[0] if isinstance(cfg.lr, Collection) else cfg.lr + if cfg.warmup_init_lr < 0: + cfg.warmup_init_lr = 0 if cfg.warmup_updates > 0 else warmup_end_lr + + # linearly warmup for the first cfg.warmup_updates + self.lr_step = (warmup_end_lr - cfg.warmup_init_lr) / cfg.warmup_updates + + # then, decay prop. to the inverse square root of the update number + self.decay_factor = warmup_end_lr * cfg.warmup_updates**0.5 + + # initial learning rate + self.lr = cfg.warmup_init_lr + self.optimizer.set_lr(self.lr) + + def step(self, epoch, val_loss=None): + """Update the learning rate at the end of the given epoch.""" + super().step(epoch, val_loss) + # we don't change the learning rate at epoch boundaries + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + if num_updates < self.cfg.warmup_updates: + self.lr = self.cfg.warmup_init_lr + num_updates * self.lr_step + else: + self.lr = self.decay_factor * num_updates**-0.5 + self.optimizer.set_lr(self.lr) + return self.lr diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/manual_lr_scheduler.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/manual_lr_scheduler.py new file mode 100644 index 00000000..57edc256 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/manual_lr_scheduler.py @@ -0,0 +1,121 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from . import LegacyFairseqLRScheduler, register_lr_scheduler +import logging +import ast + +logger = logging.getLogger(__name__) +logger.setLevel(logging.WARNING) + + +@register_lr_scheduler("manual") +class ManualSchedule(LegacyFairseqLRScheduler): + """Decay the LR on a manual schedule.""" + + def __init__(self, args, optimizer): + super().__init__(args, optimizer) + + self.epoch2lr = self.parse_manuallr_args(args.epoch2lr) + self.update2lr = self.parse_manuallr_args(args.update2lr) + logger.info("@@@ ManualSchedule epoch2lr={}".format(self.epoch2lr)) + logger.info("@@@ ManualSchedule update2lr={}".format(self.update2lr)) + + if 1 in self.epoch2lr: + self.lr = self.epoch2lr[1] + elif 1 in self.update2lr: + self.lr = self.update2lr[1] + else: + self.lr = args.lr[0] + self.optimizer.set_lr(self.lr) # Set the beginning of the epoch. + + def parse_manuallr_args(self, lr_args_str): + lr_dict = ast.literal_eval(lr_args_str.replace(" ", "")) + if not isinstance(lr_dict, dict): + raise ValueError("epoch2lr/update2lr must be abel to evaluated to a dict") + + lr_args = {} + logger.info("@@@ after parsing input dictionary lr_dict = {}".format(lr_dict)) + for key, val in lr_dict.items(): + if "," in key: + for k in key.split(","): + lr_args[int(k)] = float(val) + elif "-" in key: + s = int(key.split("-")[0]) + e = int(key.split("-")[1]) + for k in range(s, e + 1, 1): + lr_args[k] = float(val) + else: + lr_args[int(key)] = float(val) + + return lr_args + + @staticmethod + def add_args(parser): + """Add arguments to the parser for this LR scheduler.""" + # fmt: off + parser.add_argument( + "--epoch2lr", + type=str, + metavar="DICT", + default="{}", + help="a dictionary used to set lr for each epoch manually", + ) + parser.add_argument( + "--update2lr", + type=str, + metavar="DICT", + default="{}", + help="a dictionary used to set lr for each update manually", + ) + # fmt: on + + def state_dict(self): + return {"lr": self.lr} + + def load_state_dict(self, state_dict): + if "lr" in state_dict: + self.lr = state_dict["lr"] + + def get_next_lr(self, epoch): + manual_keys = [k for k in self.epoch2lr if k <= epoch] + if manual_keys: + manual_lr = self.epoch2lr[max(manual_keys)] + else: + logger.warning( + "@@@ epoch={} does not exist in manual lr input. epoch2lr={}...".format( + epoch, + list(self.epoch2lr.items())[ + : min(10, len(self.epoch2lr.keys()) - 1) + ], + ) + ) + manual_lr = self.optimizer.get_lr() + return manual_lr + + def step_begin_epoch(self, epoch): + """Update the learning rate at the beginning of the given epoch.""" + self.lr = self.get_next_lr(epoch) + self.optimizer.set_lr(self.lr) + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + manual_keys = [k for k in self.update2lr if k <= num_updates] + if manual_keys: + manual_lr = self.update2lr[max(manual_keys)] + else: + logger.warning( + "epoch={} does not exist in manual lr input update2lr={}...".format( + num_updates, + list(self.update2lr.items())[ + : min(10, len(self.update2lr.keys()) - 1) + ], + ) + ) + manual_lr = self.optimizer.get_lr() + + self.optimizer.set_lr(manual_lr) + return self.optimizer.get_lr() diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/pass_through.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/pass_through.py new file mode 100644 index 00000000..2f93db32 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/pass_through.py @@ -0,0 +1,39 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class PassThroughScheduleConfig(FairseqDataclass): + pass + + +@register_lr_scheduler("pass_through", dataclass=PassThroughScheduleConfig) +class PassThroughScheduleSchedule(FairseqLRScheduler): + """Delegate lr scheduling to the optimizer.""" + + def __init__(self, cfg: PassThroughScheduleConfig, optimizer): + super().__init__(cfg, optimizer) + assert ( + hasattr(optimizer, "lr_scheduler") and optimizer.lr_scheduler is not None + ), "Pass-through schedule can only be used with optimizers with their own schedulers" + + def state_dict(self): + return self.optimizer.lr_scheduler.state_dict() + + def load_state_dict(self, state_dict): + self.optimizer.lr_scheduler.load_state_dict(state_dict) + + def step_begin_epoch(self, epoch): + """Update the learning rate at the beginning of the given epoch.""" + return self.optimizer.lr_scheduler.step_begin_epoch(epoch) + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + return self.optimizer.lr_scheduler.step_update(num_updates) diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/polynomial_decay_schedule.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/polynomial_decay_schedule.py new file mode 100644 index 00000000..b8109a7c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/polynomial_decay_schedule.py @@ -0,0 +1,89 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +from typing import Optional, List +from omegaconf import II + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class PolynomialDecayLRScheduleConfig(FairseqDataclass): + warmup_updates: int = field( + default=0, + metadata={"help": "warmup the learning rate linearly for the first N updates"}, + ) + force_anneal: Optional[int] = field( + default=None, + metadata={"help": "force annealing at specified epoch"}, + ) + end_learning_rate: float = field( + default=0.0, + metadata={"help": "learning rate to decay to"}, + ) + power: float = field( + default=1.0, + metadata={"help": "decay exponent"}, + ) + total_num_update: float = field( + default=II("optimization.max_update"), + metadata={"help": "total number of updates over which to decay learning rate"}, + ) + lr: List[float] = II("optimization.lr") + + +@register_lr_scheduler("polynomial_decay", dataclass=PolynomialDecayLRScheduleConfig) +class PolynomialDecayLRSchedule(FairseqLRScheduler): + """Decay the LR on a fixed schedule.""" + + def __init__(self, cfg: PolynomialDecayLRScheduleConfig, optimizer): + super().__init__(cfg, optimizer) + + assert cfg.total_num_update > 0 + + self.lr = cfg.lr[0] + if cfg.warmup_updates > 0: + self.warmup_factor = 1.0 / cfg.warmup_updates + else: + self.warmup_factor = 1 + self.end_learning_rate = cfg.end_learning_rate + self.total_num_update = cfg.total_num_update + self.power = cfg.power + self.optimizer.set_lr(self.warmup_factor * self.lr) + + def get_next_lr(self, epoch): + lrs = self.cfg.lr + if self.cfg.force_anneal is None or epoch < self.cfg.force_anneal: + # use fixed LR schedule + next_lr = lrs[min(epoch, len(lrs) - 1)] + else: + # annneal based on lr_shrink + next_lr = self.optimizer.get_lr() + return next_lr + + def step_begin_epoch(self, epoch): + """Update the learning rate at the beginning of the given epoch.""" + self.lr = self.get_next_lr(epoch) + self.optimizer.set_lr(self.warmup_factor * self.lr) + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + if self.cfg.warmup_updates > 0 and num_updates <= self.cfg.warmup_updates: + self.warmup_factor = num_updates / float(self.cfg.warmup_updates) + lr = self.warmup_factor * self.lr + elif num_updates >= self.total_num_update: + lr = self.end_learning_rate + else: + warmup = self.cfg.warmup_updates + lr_range = self.lr - self.end_learning_rate + pct_remaining = 1 - (num_updates - warmup) / ( + self.total_num_update - warmup + ) + lr = lr_range * pct_remaining ** (self.power) + self.end_learning_rate + self.optimizer.set_lr(lr) + return self.optimizer.get_lr() diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/reduce_lr_on_plateau.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/reduce_lr_on_plateau.py new file mode 100644 index 00000000..5ee9c1be --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/reduce_lr_on_plateau.py @@ -0,0 +1,143 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +from typing import List + +import torch.optim.lr_scheduler +from omegaconf import II + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class ReduceLROnPlateauLRScheduleConfig(FairseqDataclass): + lr_shrink: float = field( + default=0.1, metadata={"help": "shrink factor for annealing"} + ) + lr_threshold: float = field( + default=1e-4, + metadata={ + "help": ( + "threshold for measuring the new optimum, to only focus on " + "significant changes" + ) + }, + ) + lr_patience: int = field( + default=0, + metadata={ + "help": ( + "number of epochs with no improvement after which learning rate will " + "be reduced" + ) + }, + ) + warmup_updates: int = field( + default=0, + metadata={"help": "warmup the learning rate linearly for the first N updates"}, + ) + warmup_init_lr: float = field( + default=-1, + metadata={ + "help": "initial learning rate during warmup phase; default is cfg.lr" + }, + ) + lr: List[float] = II("optimization.lr") + maximize_best_checkpoint_metric: bool = II( + "checkpoint.maximize_best_checkpoint_metric" + ) + + +@register_lr_scheduler( + "reduce_lr_on_plateau", dataclass=ReduceLROnPlateauLRScheduleConfig +) +class ReduceLROnPlateauLRSchedule(FairseqLRScheduler): + """ + Decay the LR by a factor every time the validation loss plateaus. + Also comes with optional warmup phase, where we linearly increase + the learning rate from some initial learning rate + (``--warmup-init-lr``) until the configured learning rate + (``--lr``). Thereafter the lr is adjusted according to original + reduce_on_plateau scheme. + + During warmup:: + + lrs = torch.linspace( + cfg.warmup_init_lr, cfg.lr, cfg.warmup_updates + ) + lr = lrs[update_num] + """ + + def __init__(self, cfg: ReduceLROnPlateauLRScheduleConfig, optimizer): + super().__init__(cfg, optimizer) + if len(cfg.lr) > 1: + raise ValueError( + "Cannot use a fixed learning rate schedule with reduce_lr_on_plateau." + " Consider --lr-scheduler=fixed instead." + ) + self.lr_scheduler = torch.optim.lr_scheduler.ReduceLROnPlateau( + self.optimizer.optimizer, + patience=cfg.lr_patience, + factor=cfg.lr_shrink, + mode="max" if cfg.maximize_best_checkpoint_metric else "min", + threshold=cfg.lr_threshold, + ) + warmup_end_lr = cfg.lr[0] + # if no warm up, sets initial lr to be cfg.lr[0] + if cfg.warmup_init_lr < 0: + cfg.warmup_init_lr = 0 if cfg.warmup_updates > 0 else warmup_end_lr + + # linearly warmup for the first cfg.warmup_updates + if cfg.warmup_updates > 0: + self.lr_step = (warmup_end_lr - cfg.warmup_init_lr) / cfg.warmup_updates + + # this flag is either set from arg when no warm up, or set by + # step_update() when warmup finishes + self.warmup_end = True if cfg.warmup_updates <= 0 else False + + # initial learning rate + # this self.lr is used only during init and/or warm up period + self.lr = warmup_end_lr if self.warmup_end else cfg.warmup_init_lr + self.optimizer.set_lr(self.lr) + + def state_dict(self): + """Return the LR scheduler state dict.""" + return { + "best": self.lr_scheduler.best, + "last_epoch": self.lr_scheduler.last_epoch, + } + + def load_state_dict(self, state_dict): + """Load an LR scheduler state dict.""" + self.lr_scheduler.best = state_dict["best"] + if "last_epoch" in state_dict: + self.lr_scheduler.last_epoch = state_dict["last_epoch"] + + def step(self, epoch, val_loss=None): + """ + Update the learning rate at the end of the given epoch if warmup + finishes otherwise no update of lr on epoch boundaries + """ + if val_loss is not None and self.warmup_end is True: + self.lr_scheduler.step(val_loss) + else: + self.lr_scheduler.last_epoch = epoch + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """ + Update the learning rate after each update.""" + # if there is warmup + if self.cfg.warmup_updates > 0: + if num_updates <= self.cfg.warmup_updates: + self.lr = self.cfg.warmup_init_lr + num_updates * self.lr_step + self.optimizer.set_lr(self.lr) + else: + if self.warmup_end is False: + self.warmup_end = True + # else do nothing + return self.optimizer.get_lr() diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/step_lr_scheduler.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/step_lr_scheduler.py new file mode 100644 index 00000000..db99d4ee --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/step_lr_scheduler.py @@ -0,0 +1,85 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections.abc import Collection +from dataclasses import dataclass, field +from typing import List + +from omegaconf import II + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class StepLRScheduleConfig(FairseqDataclass): + warmup_updates: int = field( + default=0, + metadata={"help": "warmup the learning rate linearly for the first N updates"}, + ) + warmup_init_lr: float = field( + default=-1, + metadata={ + "help": "initial learning rate during warmup phase; default is cfg.lr" + }, + ) + lr: List[float] = field( + default=II("optimization.lr"), + metadata={"help": "max learning rate, must be more than cfg.min_lr"}, + ) + min_lr: float = field(default=0.0, metadata={"help": "min learning rate"}) + lr_deacy_period: int = field(default=25000, metadata={"help": "decay period"}) + lr_decay: float = field(default=0.5, metadata={"help": "decay factor"}) + + +@register_lr_scheduler("step", dataclass=StepLRScheduleConfig) +class StepLRSchedule(FairseqLRScheduler): + """Decay learning rate every k updates by a fixed factor""" + + def __init__(self, cfg: StepLRScheduleConfig, fairseq_optimizer): + super().__init__(cfg, fairseq_optimizer) + self.max_lr = cfg.lr[0] if isinstance(cfg.lr, Collection) else cfg.lr + self.min_lr = cfg.min_lr + self.lr_deacy_period = cfg.lr_deacy_period + self.lr_decay = cfg.lr_decay + self.warmup_updates = cfg.warmup_updates + self.warmup_init_lr = ( + cfg.warmup_init_lr if cfg.warmup_init_lr >= 0 else self.min_lr + ) + + assert self.lr_deacy_period > 0 + assert self.lr_decay <= 1 + assert self.min_lr >= 0 + assert self.max_lr > self.min_lr + + if cfg.warmup_updates > 0: + # linearly warmup for the first cfg.warmup_updates + self.warmup_lr_step = ( + self.max_lr - self.warmup_init_lr + ) / self.warmup_updates + else: + self.warmup_lr_step = 1 + + # initial learning rate + self.lr = self.warmup_init_lr + self.optimizer.set_lr(self.lr) + + def step(self, epoch, val_loss=None): + """Update the learning rate at the end of the given epoch.""" + super().step(epoch, val_loss) + # we don't change the learning rate at epoch boundaries + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + if num_updates < self.cfg.warmup_updates: + self.lr = self.warmup_init_lr + num_updates * self.warmup_lr_step + else: + curr_updates = num_updates - self.cfg.warmup_updates + lr_mult = self.lr_decay ** (curr_updates // self.lr_deacy_period) + self.lr = max(self.max_lr * lr_mult, self.min_lr) + + self.optimizer.set_lr(self.lr) + return self.lr diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/tri_stage_lr_scheduler.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/tri_stage_lr_scheduler.py new file mode 100644 index 00000000..4d5547c3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/tri_stage_lr_scheduler.py @@ -0,0 +1,175 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass, field +from typing import Optional, List, Tuple +from omegaconf import II + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class TriStageLRScheduleConfig(FairseqDataclass): + warmup_steps: int = field( + default=0, + metadata={"help": "warmup the learning rate linearly for the first N updates"}, + ) + hold_steps: int = field( + default=0, + metadata={"help": "steps in hold stage"}, + ) + decay_steps: int = field( + default=0, + metadata={"help": "steps in decay stages"}, + ) + phase_ratio: Optional[Tuple[float, float, float]] = field( + default=None, + metadata={ + "help": ( + "if set, automatically sets warmup/hold/decay steps to the ratio " + "specified here from max_updates. the ratios must add up to 1.0" + ) + }, + ) + init_lr_scale: float = field( + default=0.01, + metadata={"help": "initial learning rate scale during warmup phase"}, + ) + final_lr_scale: float = field( + default=0.01, + metadata={"help": "final learning rate scale"}, + ) + max_update: float = II("optimization.max_update") + lr: List[float] = II("optimization.lr") + + +@register_lr_scheduler("tri_stage", dataclass=TriStageLRScheduleConfig) +class TriStageLRSchedule(FairseqLRScheduler): + """Tristage learning rate schedulr + + Implement the learning rate scheduler in https://arxiv.org/pdf/1904.08779.pdf + + Similar to inverse_squre_root scheduler, but tri_stage learning rate employs + three stages LR scheduling: + + - warmup stage, starting from `lr` * `init_lr_scale`, linearly + increased to `lr` in `warmup_steps` iterations + + - hold stage, after `warmup_steps`, keep the LR as `lr` for `hold_steps` + iterations + + - decay stage, after hold stage, decay LR exponetially to + `lr` * `final_lr_scale` in `decay_steps`; + after that LR is keep as `final_lr_scale` * `lr` + + During warmup:: + + init_lr = cfg.init_lr_scale * cfg.lr + lrs = torch.linspace(init_lr, cfg.lr, cfg.warmup_steps) + lr = lrs[update_num] + + During hold:: + + lr = cfg.lr + + During decay:: + + decay_factor = - math.log(cfg.final_lr_scale) / cfg.decay_steps + lr = cfg.lr * exp(- (update_num - warmup_steps - decay_steps) * decay_factor) + + After that:: + + lr = cfg.lr * cfg.final_lr_scale + """ + + def __init__(self, cfg: TriStageLRScheduleConfig, optimizer): + super().__init__(cfg, optimizer) + if len(cfg.lr) > 1: + raise ValueError( + "Cannot use a fixed learning rate schedule with tri-stage lr." + " Consider --lr-scheduler=fixed instead." + ) + + # calculate LR at each point + self.peak_lr = cfg.lr[0] + self.init_lr = cfg.init_lr_scale * cfg.lr[0] + self.final_lr = cfg.final_lr_scale * cfg.lr[0] + + if cfg.phase_ratio is not None: + assert cfg.max_update > 0 + assert sum(cfg.phase_ratio) == 1, "phase ratios must add up to 1" + self.warmup_steps = int(cfg.max_update * cfg.phase_ratio[0]) + self.hold_steps = int(cfg.max_update * cfg.phase_ratio[1]) + self.decay_steps = int(cfg.max_update * cfg.phase_ratio[2]) + else: + self.warmup_steps = cfg.warmup_steps + self.hold_steps = cfg.hold_steps + self.decay_steps = cfg.decay_steps + + assert ( + self.warmup_steps + self.hold_steps + self.decay_steps > 0 + ), "please specify steps or phase_ratio" + + self.warmup_rate = ( + (self.peak_lr - self.init_lr) / self.warmup_steps + if self.warmup_steps != 0 + else 0 + ) + self.decay_factor = -math.log(cfg.final_lr_scale) / self.decay_steps + + # initial learning rate + self.lr = self.init_lr + self.optimizer.set_lr(self.lr) + + def _decide_stage(self, update_step): + """ + return stage, and the corresponding steps within the current stage + """ + if update_step < self.warmup_steps: + # warmup state + return 0, update_step + + offset = self.warmup_steps + + if update_step < offset + self.hold_steps: + # hold stage + return 1, update_step - offset + + offset += self.hold_steps + + if update_step <= offset + self.decay_steps: + # decay stage + return 2, update_step - offset + + offset += self.decay_steps + + # still here ? constant lr stage + return 3, update_step - offset + + def step(self, epoch, val_loss=None): + """Update the learning rate at the end of the given epoch.""" + super().step(epoch, val_loss) + # we don't change the learning rate at epoch boundaries + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + stage, steps_in_stage = self._decide_stage(num_updates) + if stage == 0: + self.lr = self.init_lr + self.warmup_rate * steps_in_stage + elif stage == 1: + self.lr = self.peak_lr + elif stage == 2: + self.lr = self.peak_lr * math.exp(-self.decay_factor * steps_in_stage) + elif stage == 3: + self.lr = self.final_lr + else: + raise ValueError("Undefined stage") + + self.optimizer.set_lr(self.lr) + + return self.lr diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/triangular_lr_scheduler.py b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/triangular_lr_scheduler.py new file mode 100644 index 00000000..2a32bd10 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/lr_scheduler/triangular_lr_scheduler.py @@ -0,0 +1,83 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from dataclasses import dataclass, field +from typing import List + +from omegaconf import II + +from fairseq.dataclass import FairseqDataclass +from fairseq.optim.lr_scheduler import FairseqLRScheduler, register_lr_scheduler + + +@dataclass +class TriangularLRScheduleConfig(FairseqDataclass): + max_lr: float = field( + default="???", metadata={"help": "max learning rate, must be more than cfg.lr"} + ) + lr_period_updates: float = field( + default=5000, + metadata={"help": "initial number of updates per period (cycle length)"}, + ) + lr_shrink: float = field( + default=0.1, metadata={"help": "shrink factor for annealing"} + ) + shrink_min: bool = field( + default=False, metadata={"help": "if set, also shrinks min lr"} + ) + lr: List[float] = II("optimization.lr") + + +@register_lr_scheduler("triangular", dataclass=TriangularLRScheduleConfig) +class TriangularLRSchedule(FairseqLRScheduler): + """Assign LR based on a triangular cyclical schedule. + + See https://arxiv.org/pdf/1506.01186.pdf for details. + """ + + def __init__(self, cfg: TriangularLRScheduleConfig, optimizer): + super().__init__(cfg, optimizer) + if len(cfg.lr) > 1: + raise ValueError( + "Cannot use a fixed learning rate schedule with triangular." + " Consider --lr-scheduler=fixed instead." + ) + + lr = cfg.lr[0] + + assert cfg.max_lr > lr, "max_lr must be more than lr" + self.min_lr = lr + self.max_lr = cfg.max_lr + self.stepsize = cfg.lr_period_updates // 2 + self.lr_shrink = cfg.lr_shrink + self.shrink_min = cfg.shrink_min + + # initial learning rate + self.lr = self.min_lr + self.optimizer.set_lr(self.lr) + + def step(self, epoch, val_loss=None): + """Update the learning rate at the end of the given epoch.""" + super().step(epoch, val_loss) + # we don't change the learning rate at epoch boundaries + return self.optimizer.get_lr() + + def step_update(self, num_updates): + """Update the learning rate after each update.""" + cycle = math.floor(num_updates / (2 * self.stepsize)) + + lr_shrink = self.lr_shrink**cycle + max_lr = self.max_lr * lr_shrink + if self.shrink_min: + min_lr = self.min_lr * lr_shrink + else: + min_lr = self.min_lr + + x = abs(num_updates / self.stepsize - 2 * (cycle + 1) + 1) + self.lr = min_lr + (max_lr - min_lr) * max(0, (1 - x)) + + self.optimizer.set_lr(self.lr) + return self.lr diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/nag.py b/PyTorch/NLP/new-Transformer/fairseq/optim/nag.py new file mode 100644 index 00000000..c30a6c0f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/nag.py @@ -0,0 +1,111 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from collections.abc import Collection +from dataclasses import dataclass, field +from typing import List + +import torch +from fairseq.dataclass import FairseqDataclass +from omegaconf import II, DictConfig +from torch.optim.optimizer import Optimizer, required + +from . import FairseqOptimizer, register_optimizer + + +@dataclass +class FairseqNAGConfig(FairseqDataclass): + momentum: float = field(default=0.99, metadata={"help": "momentum factor"}) + weight_decay: float = field(default=0.0, metadata={"help": "weight decay"}) + # TODO common vars in parent class + lr: List[float] = II("optimization.lr") + + +@register_optimizer("nag", dataclass=FairseqNAGConfig) +class FairseqNAG(FairseqOptimizer): + def __init__(self, cfg: DictConfig, params): + super().__init__(cfg) + self._optimizer = NAG(params, **self.optimizer_config) + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + return { + "lr": self.cfg.lr[0] + if isinstance(self.cfg.lr, Collection) + else self.cfg.lr, + "momentum": self.cfg.momentum, + "weight_decay": self.cfg.weight_decay, + } + + +class NAG(Optimizer): + def __init__(self, params, lr=required, momentum=0, weight_decay=0): + defaults = dict(lr=lr, lr_old=lr, momentum=momentum, weight_decay=weight_decay) + super(NAG, self).__init__(params, defaults) + + @property + def supports_memory_efficient_fp16(self): + return True + + @property + def supports_flat_params(self): + return True + + def step(self, closure=None): + """Performs a single optimization step. + + Args: + closure (callable, optional): A closure that reevaluates the model + and returns the loss. + """ + loss = None + if closure is not None: + loss = closure() + + for group in self.param_groups: + weight_decay = group["weight_decay"] + momentum = group["momentum"] + lr = group["lr"] + lr_old = group.get("lr_old", lr) + lr_correct = lr / lr_old if lr_old > 0 else lr + + for p in group["params"]: + if p.grad is None: + continue + + p_data_fp32 = p.data + if p_data_fp32.dtype in {torch.float16, torch.bfloat16}: + p_data_fp32 = p_data_fp32.float() + + d_p = p.grad.data.float() + param_state = self.state[p] + if "momentum_buffer" not in param_state: + param_state["momentum_buffer"] = torch.zeros_like(d_p) + else: + param_state["momentum_buffer"] = param_state["momentum_buffer"].to( + d_p + ) + + buf = param_state["momentum_buffer"] + + if weight_decay != 0: + p_data_fp32.mul_(1 - lr * weight_decay) + p_data_fp32.add_(buf, alpha=momentum * momentum * lr_correct) + p_data_fp32.add_(d_p, alpha=-(1 + momentum) * lr) + + buf.mul_(momentum * lr_correct).add_(d_p, alpha=-lr) + + if p.data.dtype in {torch.float16, torch.bfloat16}: + p.data.copy_(p_data_fp32) + + group["lr_old"] = lr + + return loss diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/sgd.py b/PyTorch/NLP/new-Transformer/fairseq/optim/sgd.py new file mode 100644 index 00000000..8e34fb99 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/sgd.py @@ -0,0 +1,43 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch.optim + +from . import LegacyFairseqOptimizer, register_optimizer + + +@register_optimizer("sgd") +class SGD(LegacyFairseqOptimizer): + def __init__(self, args, params): + super().__init__(args) + self._optimizer = torch.optim.SGD(params, **self.optimizer_config) + + @staticmethod + def add_args(parser): + """Add optimizer-specific arguments to the parser.""" + # fmt: off + parser.add_argument('--momentum', default=0.0, type=float, metavar='M', + help='momentum factor') + parser.add_argument('--weight-decay', '--wd', default=0.0, type=float, metavar='WD', + help='weight decay') + # fmt: on + + @property + def optimizer_config(self): + """ + Return a kwarg dictionary that will be used to override optimizer + args stored in checkpoints. This allows us to load a checkpoint and + resume training using a different set of optimizer args, e.g., with a + different learning rate. + """ + return { + "lr": self.args.lr[0], + "momentum": self.args.momentum, + "weight_decay": self.args.weight_decay, + } + + @property + def supports_flat_params(self): + return True diff --git a/PyTorch/NLP/new-Transformer/fairseq/optim/shard.py b/PyTorch/NLP/new-Transformer/fairseq/optim/shard.py new file mode 100644 index 00000000..9d7f2eb9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/optim/shard.py @@ -0,0 +1,58 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from typing import Any, Dict + +from fairseq.distributed import utils + + +try: + from fairscale.optim import OSS + + _has_fairscale = True +except ImportError: + _has_fairscale = False + + +def shard_(optimizer, group): + if not _has_fairscale: + raise ImportError( + "\n\nPlease install the fairscale package:" "\n\n pip install fairscale" + ) + + class FairseqOSS(OSS): + @property + def disable_mem_eff_fp16_loading_hack(self): + return True + + def __getattr__(self, name): + if name.startswith("supports") and hasattr(self.optim, name): + return getattr(self.optim, name) + raise AttributeError( + "'FairseqOSS' object has no attribute {0!r}".format(name) + ) + + def broadcast_global_state_dict( + self, state_dict: Dict[str, Any] + ) -> Dict[str, Any]: + """ + Broadcasts the entire state_dict to all other ranks + each rank is responsible to load their own partition of data + """ + return utils.broadcast_object( + state_dict, + src_rank=0, + group=self.group, + ) + + torch_optimizer = optimizer.optimizer + optim_cls = type(torch_optimizer) + + optimizer.optimizer = FairseqOSS( + torch_optimizer.param_groups, + optim_cls, + group=group, + **optimizer.optimizer_config + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/options.py b/PyTorch/NLP/new-Transformer/fairseq/options.py new file mode 100644 index 00000000..92059163 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/options.py @@ -0,0 +1,413 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import argparse +from pathlib import Path +from typing import Callable, List, Optional, Union + +import torch +from fairseq import utils +from fairseq.data.indexed_dataset import get_available_dataset_impl +from fairseq.dataclass.configs import ( + CheckpointConfig, + CommonConfig, + CommonEvalConfig, + DatasetConfig, + DistributedTrainingConfig, + EvalLMConfig, + GenerationConfig, + InteractiveConfig, + OptimizationConfig, + EMAConfig, +) +from fairseq.dataclass.utils import gen_parser_from_dataclass + +# this import is for backward compatibility +from fairseq.utils import csv_str_list, eval_bool, eval_str_dict, eval_str_list # noqa + + +def get_preprocessing_parser(default_task="translation"): + parser = get_parser("Preprocessing", default_task) + add_preprocess_args(parser) + return parser + + +def get_training_parser(default_task="translation"): + parser = get_parser("Trainer", default_task) + add_dataset_args(parser, train=True) + add_distributed_training_args(parser) + add_model_args(parser) + add_optimization_args(parser) + add_checkpoint_args(parser) + add_ema_args(parser) + return parser + + +def get_generation_parser(interactive=False, default_task="translation"): + parser = get_parser("Generation", default_task) + add_dataset_args(parser, gen=True) + add_distributed_training_args(parser, default_world_size=1) + add_generation_args(parser) + add_checkpoint_args(parser) + if interactive: + add_interactive_args(parser) + return parser + + +def get_speech_generation_parser(default_task="text_to_speech"): + parser = get_parser("Speech Generation", default_task) + add_dataset_args(parser, gen=True) + add_distributed_training_args(parser, default_world_size=1) + add_speech_generation_args(parser) + return parser + + +def get_interactive_generation_parser(default_task="translation"): + return get_generation_parser(interactive=True, default_task=default_task) + + +def get_eval_lm_parser(default_task="language_modeling"): + parser = get_parser("Evaluate Language Model", default_task) + add_dataset_args(parser, gen=True) + add_distributed_training_args(parser, default_world_size=1) + add_eval_lm_args(parser) + return parser + + +def get_validation_parser(default_task=None): + parser = get_parser("Validation", default_task) + add_dataset_args(parser, train=True) + add_distributed_training_args(parser, default_world_size=1) + group = parser.add_argument_group("Evaluation") + gen_parser_from_dataclass(group, CommonEvalConfig()) + return parser + + +def parse_args_and_arch( + parser: argparse.ArgumentParser, + input_args: List[str] = None, + parse_known: bool = False, + suppress_defaults: bool = False, + modify_parser: Optional[Callable[[argparse.ArgumentParser], None]] = None, +): + """ + Args: + parser (ArgumentParser): the parser + input_args (List[str]): strings to parse, defaults to sys.argv + parse_known (bool): only parse known arguments, similar to + `ArgumentParser.parse_known_args` + suppress_defaults (bool): parse while ignoring all default values + modify_parser (Optional[Callable[[ArgumentParser], None]]): + function to modify the parser, e.g., to set default values + """ + if suppress_defaults: + # Parse args without any default values. This requires us to parse + # twice, once to identify all the necessary task/model args, and a second + # time with all defaults set to None. + args = parse_args_and_arch( + parser, + input_args=input_args, + parse_known=parse_known, + suppress_defaults=False, + ) + suppressed_parser = argparse.ArgumentParser(add_help=False, parents=[parser]) + suppressed_parser.set_defaults(**{k: None for k, v in vars(args).items()}) + args = suppressed_parser.parse_args(input_args) + return argparse.Namespace( + **{k: v for k, v in vars(args).items() if v is not None} + ) + + from fairseq.models import ARCH_MODEL_REGISTRY, ARCH_CONFIG_REGISTRY, MODEL_REGISTRY + + # Before creating the true parser, we need to import optional user module + # in order to eagerly import custom tasks, optimizers, architectures, etc. + usr_parser = argparse.ArgumentParser(add_help=False, allow_abbrev=False) + usr_parser.add_argument("--user-dir", default=None) + usr_args, _ = usr_parser.parse_known_args(input_args) + utils.import_user_module(usr_args) + + if modify_parser is not None: + modify_parser(parser) + + # The parser doesn't know about model/criterion/optimizer-specific args, so + # we parse twice. First we parse the model/criterion/optimizer, then we + # parse a second time after adding the *-specific arguments. + # If input_args is given, we will parse those args instead of sys.argv. + args, _ = parser.parse_known_args(input_args) + + # Add model-specific args to parser. + if hasattr(args, "arch"): + model_specific_group = parser.add_argument_group( + "Model-specific configuration", + # Only include attributes which are explicitly given as command-line + # arguments or which have default values. + argument_default=argparse.SUPPRESS, + ) + if args.arch in ARCH_MODEL_REGISTRY: + ARCH_MODEL_REGISTRY[args.arch].add_args(model_specific_group) + elif args.arch in MODEL_REGISTRY: + MODEL_REGISTRY[args.arch].add_args(model_specific_group) + else: + raise RuntimeError() + + if hasattr(args, "task"): + from fairseq.tasks import TASK_REGISTRY + + TASK_REGISTRY[args.task].add_args(parser) + if getattr(args, "use_bmuf", False): + # hack to support extra args for block distributed data parallelism + from fairseq.optim.bmuf import FairseqBMUF + + FairseqBMUF.add_args(parser) + + # Add *-specific args to parser. + from fairseq.registry import REGISTRIES + + for registry_name, REGISTRY in REGISTRIES.items(): + choice = getattr(args, registry_name, None) + if choice is not None: + cls = REGISTRY["registry"][choice] + if hasattr(cls, "add_args"): + cls.add_args(parser) + elif hasattr(cls, "__dataclass"): + gen_parser_from_dataclass(parser, cls.__dataclass()) + + # Modify the parser a second time, since defaults may have been reset + if modify_parser is not None: + modify_parser(parser) + + # Parse a second time. + if parse_known: + args, extra = parser.parse_known_args(input_args) + else: + args = parser.parse_args(input_args) + extra = None + # Post-process args. + if ( + hasattr(args, "batch_size_valid") and args.batch_size_valid is None + ) or not hasattr(args, "batch_size_valid"): + args.batch_size_valid = args.batch_size + if hasattr(args, "max_tokens_valid") and args.max_tokens_valid is None: + args.max_tokens_valid = args.max_tokens + if getattr(args, "memory_efficient_fp16", False): + args.fp16 = True + if getattr(args, "memory_efficient_bf16", False): + args.bf16 = True + args.tpu = getattr(args, "tpu", False) + args.bf16 = getattr(args, "bf16", False) + if args.bf16: + args.tpu = True + if args.tpu and args.fp16: + raise ValueError("Cannot combine --fp16 and --tpu, use --bf16 on TPUs") + + if getattr(args, "seed", None) is None: + args.seed = 1 # default seed for training + args.no_seed_provided = True + else: + args.no_seed_provided = False + + if getattr(args, "update_epoch_batch_itr", None) is None: + if hasattr(args, "grouped_shuffling"): + args.update_epoch_batch_itr = args.grouped_shuffling + else: + args.grouped_shuffling = False + args.update_epoch_batch_itr = False + + # Apply architecture configuration. + if hasattr(args, "arch") and args.arch in ARCH_CONFIG_REGISTRY: + ARCH_CONFIG_REGISTRY[args.arch](args) + + if parse_known: + return args, extra + else: + return args + + +def get_parser(desc, default_task="translation"): + # Before creating the true parser, we need to import optional user module + # in order to eagerly import custom tasks, optimizers, architectures, etc. + usr_parser = argparse.ArgumentParser(add_help=False, allow_abbrev=False) + usr_parser.add_argument("--user-dir", default=None) + usr_args, _ = usr_parser.parse_known_args() + utils.import_user_module(usr_args) + + parser = argparse.ArgumentParser(allow_abbrev=False) + gen_parser_from_dataclass(parser, CommonConfig()) + + from fairseq.registry import REGISTRIES + + for registry_name, REGISTRY in REGISTRIES.items(): + parser.add_argument( + "--" + registry_name.replace("_", "-"), + default=REGISTRY["default"], + choices=REGISTRY["registry"].keys(), + ) + + # Task definitions can be found under fairseq/tasks/ + from fairseq.tasks import TASK_REGISTRY + + parser.add_argument( + "--task", + metavar="TASK", + default=default_task, + choices=TASK_REGISTRY.keys(), + help="task", + ) + # fmt: on + return parser + + +def add_preprocess_args(parser): + group = parser.add_argument_group("Preprocessing") + # fmt: off + group.add_argument("-s", "--source-lang", default=None, metavar="SRC", + help="source language") + group.add_argument("-t", "--target-lang", default=None, metavar="TARGET", + help="target language") + group.add_argument("--trainpref", metavar="FP", default=None, + help="train file prefix (also used to build dictionaries)") + group.add_argument("--validpref", metavar="FP", default=None, + help="comma separated, valid file prefixes " + "(words missing from train set are replaced with )") + group.add_argument("--testpref", metavar="FP", default=None, + help="comma separated, test file prefixes " + "(words missing from train set are replaced with )") + group.add_argument("--align-suffix", metavar="FP", default=None, + help="alignment file suffix") + group.add_argument("--destdir", metavar="DIR", default="data-bin", + help="destination dir") + group.add_argument("--thresholdtgt", metavar="N", default=0, type=int, + help="map words appearing less than threshold times to unknown") + group.add_argument("--thresholdsrc", metavar="N", default=0, type=int, + help="map words appearing less than threshold times to unknown") + group.add_argument("--tgtdict", metavar="FP", + help="reuse given target dictionary") + group.add_argument("--srcdict", metavar="FP", + help="reuse given source dictionary") + group.add_argument("--nwordstgt", metavar="N", default=-1, type=int, + help="number of target words to retain") + group.add_argument("--nwordssrc", metavar="N", default=-1, type=int, + help="number of source words to retain") + group.add_argument("--alignfile", metavar="ALIGN", default=None, + help="an alignment file (optional)") + parser.add_argument('--dataset-impl', metavar='FORMAT', default='mmap', + choices=get_available_dataset_impl(), + help='output dataset implementation') + group.add_argument("--joined-dictionary", action="store_true", + help="Generate joined dictionary") + group.add_argument("--only-source", action="store_true", + help="Only process the source language") + group.add_argument("--padding-factor", metavar="N", default=8, type=int, + help="Pad dictionary size to be multiple of N") + group.add_argument("--workers", metavar="N", default=1, type=int, + help="number of parallel workers") + group.add_argument("--dict-only", action='store_true', + help="if true, only builds a dictionary and then exits") + # fmt: on + return parser + + +def add_dataset_args(parser, train=False, gen=False): + group = parser.add_argument_group("dataset_data_loading") + gen_parser_from_dataclass(group, DatasetConfig()) + # fmt: on + return group + + +def add_distributed_training_args(parser, default_world_size=None): + group = parser.add_argument_group("distributed_training") + if default_world_size is None: + default_world_size = max(1, torch.cuda.device_count()) + gen_parser_from_dataclass( + group, DistributedTrainingConfig(distributed_world_size=default_world_size) + ) + return group + + +def add_optimization_args(parser): + group = parser.add_argument_group("optimization") + # fmt: off + gen_parser_from_dataclass(group, OptimizationConfig()) + # fmt: on + return group + + +def add_checkpoint_args(parser): + group = parser.add_argument_group("checkpoint") + # fmt: off + gen_parser_from_dataclass(group, CheckpointConfig()) + # fmt: on + return group + + +def add_common_eval_args(group): + gen_parser_from_dataclass(group, CommonEvalConfig()) + + +def add_eval_lm_args(parser): + group = parser.add_argument_group("LM Evaluation") + add_common_eval_args(group) + gen_parser_from_dataclass(group, EvalLMConfig()) + + +def add_generation_args(parser): + group = parser.add_argument_group("Generation") + add_common_eval_args(group) + gen_parser_from_dataclass(group, GenerationConfig()) + return group + + +def add_speech_generation_args(parser): + group = parser.add_argument_group("Speech Generation") + add_common_eval_args(group) # NOTE: remove_bpe is not needed + # fmt: off + group.add_argument('--eos_prob_threshold', default=0.5, type=float, + help='terminate when eos probability exceeds this') + # fmt: on + return group + + +def add_interactive_args(parser): + group = parser.add_argument_group("Interactive") + gen_parser_from_dataclass(group, InteractiveConfig()) + + +def add_model_args(parser): + group = parser.add_argument_group("Model configuration") + # fmt: off + + # Model definitions can be found under fairseq/models/ + # + # The model architecture can be specified in several ways. + # In increasing order of priority: + # 1) model defaults (lowest priority) + # 2) --arch argument + # 3) --encoder/decoder-* arguments (highest priority) + from fairseq.models import ARCH_MODEL_REGISTRY + group.add_argument('--arch', '-a', metavar='ARCH', + choices=ARCH_MODEL_REGISTRY.keys(), + help='model architecture') + # fmt: on + return group + + +def get_args( + data: Union[str, Path], + task: str = "translation", + arch: str = "transformer", + **overrides +): + parser = get_training_parser(task) + args = parse_args_and_arch(parser, [str(data), "--task", task, "--arch", arch]) + + for k, v in overrides.items(): + setattr(args, k, v) + + return args + + +def add_ema_args(parser): + group = parser.add_argument_group("EMA configuration") + gen_parser_from_dataclass(group, EMAConfig()) diff --git a/PyTorch/NLP/new-Transformer/fairseq/pdb.py b/PyTorch/NLP/new-Transformer/fairseq/pdb.py new file mode 100644 index 00000000..1ba6ef0d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/pdb.py @@ -0,0 +1,47 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import multiprocessing +import os +import pdb +import sys + + +__all__ = ["set_trace"] + + +_stdin = [None] +_stdin_lock = multiprocessing.Lock() +try: + _stdin_fd = sys.stdin.fileno() +except Exception: + _stdin_fd = None + + +class MultiprocessingPdb(pdb.Pdb): + """A Pdb wrapper that works in a multiprocessing environment. + + Usage: `from fairseq import pdb; pdb.set_trace()` + """ + + def __init__(self): + pdb.Pdb.__init__(self, nosigint=True) + + def _cmdloop(self): + stdin_bak = sys.stdin + with _stdin_lock: + try: + if _stdin_fd is not None: + if not _stdin[0]: + _stdin[0] = os.fdopen(_stdin_fd) + sys.stdin = _stdin[0] + self.cmdloop() + finally: + sys.stdin = stdin_bak + + +def set_trace(): + pdb = MultiprocessingPdb() + pdb.set_trace(sys._getframe().f_back) diff --git a/PyTorch/NLP/new-Transformer/fairseq/quantization_utils.py b/PyTorch/NLP/new-Transformer/fairseq/quantization_utils.py new file mode 100644 index 00000000..11fc414c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/quantization_utils.py @@ -0,0 +1,143 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +from fairseq.modules.quantization import pq, quantization_options, scalar +from omegaconf import DictConfig + + +logger = logging.getLogger(__name__) + + +def quantize_model_scalar(model, model_cfg: DictConfig): + quant_noise_scalar = getattr(model_cfg, "quant_noise_scalar", 0) or 0 + if quant_noise_scalar > 0: + # quantize_model edits the model in place + scalar.quantize_model_(model, p=quant_noise_scalar, bits=8, update_step=1000) + return model + + +class Quantizer(object): + def __init__(self, config_path, max_epoch, max_update): + try: + import yaml + except ImportError: + raise ImportError("Please install yaml with: pip install yaml") + + # parse config + if config_path: + with open(config_path) as config_file: + config = quantization_options.parse_config_yaml( + yaml.safe_load(config_file) + ) + else: + config = quantization_options.parse_config_yaml({}) + + self.n_centroids_config = config["n_centroids"] + self.block_sizes_config = config["block_sizes"] + self.layers_to_quantize = config["layers_to_quantize"] + + # We assume that training will run for a fixed number of epochs + # (or updates) and that we should train for equal durations + # between iterations of PQ. + num_iterations = len(self.layers_to_quantize) + if max_epoch > 0: + assert max_epoch % num_iterations == 0, ( + "for iterative PQ, --max-epoch (={}) must be evenly divisible by " + "len(layers_to_quantize) (={})".format(max_epoch, num_iterations) + ) + self.epoch_schedule = max_epoch // num_iterations + else: + self.epoch_schedule = None + if max_update > 0: + assert max_update % num_iterations == 0, ( + "for iterative PQ, --max-update (={}) must be evenly divisible by " + "len(layers_to_quantize) (={})".format(max_update, num_iterations) + ) + self.update_schedule = max_update // num_iterations + else: + self.update_schedule = None + assert (self.epoch_schedule is not None) ^ ( + self.update_schedule is not None + ), "for iterative PQ, cannot specify both --max-update and --max-epoch" + + # 0 is a special value for quantization step, which will force + # the first call to begin_epoch() to call step() + self.quantization_step = 0 + + def set_trainer(self, trainer): + self.trainer = trainer + self.size_tracker = pq.SizeTracker(self.trainer.get_model()) + + def step(self): + """Move to the next stage of quantization.""" + if self.quantization_step >= len(self.layers_to_quantize): + # Maybe we just finished the last training step or we loaded + # a checkpoint for an iterative PQ model which previously + # finished training. Either way, don't quantize again. + return + + logger.info( + "quantizing model (step={}; layers_to_quantize[step]={})".format( + self.quantization_step, self.layers_to_quantize[self.quantization_step] + ) + ) + quantized_layers = pq.quantize_model_( + self.trainer.get_model(), + self.size_tracker, + self.layers_to_quantize, + self.block_sizes_config, + self.n_centroids_config, + step=self.quantization_step, + ) + logger.info("quantized layers: {}".format(quantized_layers)) + logger.info(self.size_tracker) + + self.quantization_step += 1 + + # reintialize the Trainer since model parameters have changed + self.trainer.reinitialize() + + def begin_epoch(self, epoch): + """Called at the beginning of each epoch (epochs start at 1).""" + if ( + ( + self.epoch_schedule is not None + and epoch > 0 + and (epoch - 1) % self.epoch_schedule == 0 + ) + # we always step once in the beginning, even if using + # update-based quantization + or self.quantization_step == 0 + ): + self.step() + + def step_update(self, num_updates): + """Called at the end of each step.""" + if ( + self.update_schedule is not None + and num_updates > 0 + and num_updates % self.update_schedule == 0 + ): + self.step() + + def state_dict(self): + return { + "n_centroids_config": self.n_centroids_config, + "block_sizes_config": self.block_sizes_config, + "layers_to_quantize": self.layers_to_quantize, + "epoch_schedule": self.epoch_schedule, + "update_schedule": self.update_schedule, + "quantization_step": self.quantization_step, + } + + def load_state_dict(self, state_dict): + self.n_centroids_config = state_dict["n_centroids_config"] + self.block_sizes_config = state_dict["block_sizes_config"] + self.layers_to_quantize = state_dict["layers_to_quantize"] + self.epoch_schedule = state_dict["epoch_schedule"] + self.update_schedule = state_dict["update_schedule"] + self.quantization_step = state_dict["quantization_step"] diff --git a/PyTorch/NLP/new-Transformer/fairseq/registry.py b/PyTorch/NLP/new-Transformer/fairseq/registry.py new file mode 100644 index 00000000..f3b94060 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/registry.py @@ -0,0 +1,100 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from argparse import Namespace + +from typing import Union +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.utils import merge_with_parent +from hydra.core.config_store import ConfigStore +from omegaconf import DictConfig + +REGISTRIES = {} + + +def setup_registry(registry_name: str, base_class=None, default=None, required=False): + assert registry_name.startswith("--") + registry_name = registry_name[2:].replace("-", "_") + + REGISTRY = {} + REGISTRY_CLASS_NAMES = set() + DATACLASS_REGISTRY = {} + + # maintain a registry of all registries + if registry_name in REGISTRIES: + return # registry already exists + REGISTRIES[registry_name] = { + "registry": REGISTRY, + "default": default, + "dataclass_registry": DATACLASS_REGISTRY, + } + + def build_x(cfg: Union[DictConfig, str, Namespace], *extra_args, **extra_kwargs): + if isinstance(cfg, DictConfig): + choice = cfg._name + + if choice and choice in DATACLASS_REGISTRY: + dc = DATACLASS_REGISTRY[choice] + cfg = merge_with_parent(dc(), cfg) + elif isinstance(cfg, str): + choice = cfg + if choice in DATACLASS_REGISTRY: + cfg = DATACLASS_REGISTRY[choice]() + else: + choice = getattr(cfg, registry_name, None) + if choice in DATACLASS_REGISTRY: + cfg = DATACLASS_REGISTRY[choice].from_namespace(cfg) + + if choice is None: + if required: + raise ValueError("{} is required!".format(registry_name)) + return None + + cls = REGISTRY[choice] + if hasattr(cls, "build_" + registry_name): + builder = getattr(cls, "build_" + registry_name) + else: + builder = cls + + return builder(cfg, *extra_args, **extra_kwargs) + + def register_x(name, dataclass=None): + def register_x_cls(cls): + if name in REGISTRY: + raise ValueError( + "Cannot register duplicate {} ({})".format(registry_name, name) + ) + if cls.__name__ in REGISTRY_CLASS_NAMES: + raise ValueError( + "Cannot register {} with duplicate class name ({})".format( + registry_name, cls.__name__ + ) + ) + if base_class is not None and not issubclass(cls, base_class): + raise ValueError( + "{} must extend {}".format(cls.__name__, base_class.__name__) + ) + + if dataclass is not None and not issubclass(dataclass, FairseqDataclass): + raise ValueError( + "Dataclass {} must extend FairseqDataclass".format(dataclass) + ) + + cls.__dataclass = dataclass + if cls.__dataclass is not None: + DATACLASS_REGISTRY[name] = cls.__dataclass + + cs = ConfigStore.instance() + node = dataclass() + node._name = name + cs.store(name=name, group=registry_name, node=node, provider="fairseq") + + REGISTRY[name] = cls + + return cls + + return register_x_cls + + return build_x, register_x, REGISTRY, DATACLASS_REGISTRY diff --git a/PyTorch/NLP/new-Transformer/fairseq/scoring/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/scoring/__init__.py new file mode 100644 index 00000000..58f2f563 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/scoring/__init__.py @@ -0,0 +1,55 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +import importlib +import os +from abc import ABC, abstractmethod + +from fairseq import registry +from omegaconf import DictConfig + + +class BaseScorer(ABC): + def __init__(self, cfg): + self.cfg = cfg + self.ref = [] + self.pred = [] + + def add_string(self, ref, pred): + self.ref.append(ref) + self.pred.append(pred) + + @abstractmethod + def score(self) -> float: + pass + + @abstractmethod + def result_string(self) -> str: + pass + + +_build_scorer, register_scorer, SCORER_REGISTRY, _ = registry.setup_registry( + "--scoring", default="bleu" +) + + +def build_scorer(choice, tgt_dict): + _choice = choice._name if isinstance(choice, DictConfig) else choice + + if _choice == "bleu": + from fairseq.scoring import bleu + + return bleu.Scorer( + bleu.BleuConfig(pad=tgt_dict.pad(), eos=tgt_dict.eos(), unk=tgt_dict.unk()) + ) + return _build_scorer(choice) + + +# automatically import any Python files in the current directory +for file in sorted(os.listdir(os.path.dirname(__file__))): + if file.endswith(".py") and not file.startswith("_"): + module = file[: file.find(".py")] + importlib.import_module("fairseq.scoring." + module) diff --git a/PyTorch/NLP/new-Transformer/fairseq/scoring/bertscore.py b/PyTorch/NLP/new-Transformer/fairseq/scoring/bertscore.py new file mode 100644 index 00000000..6d5a8450 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/scoring/bertscore.py @@ -0,0 +1,44 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field + +import numpy as np + +from fairseq.dataclass import FairseqDataclass +from fairseq.scoring import BaseScorer, register_scorer + + +@dataclass +class BertScoreScorerConfig(FairseqDataclass): + bert_score_lang: str = field(default="en", metadata={"help": "BERTScore language"}) + + +@register_scorer("bert_score", dataclass=BertScoreScorerConfig) +class BertScoreScorer(BaseScorer): + def __init__(self, cfg): + super(BertScoreScorer, self).__init__(cfg) + try: + import bert_score as _bert_score + except ImportError: + raise ImportError("Please install BERTScore: pip install bert-score") + + self.cfg = cfg + self._bert_score = _bert_score + self.scores = None + + def add_string(self, ref, pred): + self.ref.append(ref) + self.pred.append(pred) + + def score(self, order=4): + _, _, self.scores = self._bert_score.score( + self.pred, self.ref, lang=self.cfg.bert_score_lang + ) + self.scores = self.scores.numpy() + return np.mean(self.scores) + + def result_string(self, order=4): + return f"BERTScore: {self.score():.4f}" diff --git a/PyTorch/NLP/new-Transformer/fairseq/scoring/bleu.py b/PyTorch/NLP/new-Transformer/fairseq/scoring/bleu.py new file mode 100644 index 00000000..e55bd2f3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/scoring/bleu.py @@ -0,0 +1,168 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import ctypes +import math +import sys +from dataclasses import dataclass, field + +import torch +from fairseq.dataclass import FairseqDataclass +from fairseq.scoring import BaseScorer, register_scorer +from fairseq.scoring.tokenizer import EvaluationTokenizer + + +class BleuStat(ctypes.Structure): + _fields_ = [ + ("reflen", ctypes.c_size_t), + ("predlen", ctypes.c_size_t), + ("match1", ctypes.c_size_t), + ("count1", ctypes.c_size_t), + ("match2", ctypes.c_size_t), + ("count2", ctypes.c_size_t), + ("match3", ctypes.c_size_t), + ("count3", ctypes.c_size_t), + ("match4", ctypes.c_size_t), + ("count4", ctypes.c_size_t), + ] + + +@dataclass +class SacrebleuConfig(FairseqDataclass): + sacrebleu_tokenizer: EvaluationTokenizer.ALL_TOKENIZER_TYPES = field( + default="13a", metadata={"help": "tokenizer"} + ) + sacrebleu_lowercase: bool = field( + default=False, metadata={"help": "apply lowercasing"} + ) + sacrebleu_char_level: bool = field( + default=False, metadata={"help": "evaluate at character level"} + ) + + +@register_scorer("sacrebleu", dataclass=SacrebleuConfig) +class SacrebleuScorer(BaseScorer): + def __init__(self, cfg): + super(SacrebleuScorer, self).__init__(cfg) + import sacrebleu + + self.sacrebleu = sacrebleu + self.tokenizer = EvaluationTokenizer( + tokenizer_type=cfg.sacrebleu_tokenizer, + lowercase=cfg.sacrebleu_lowercase, + character_tokenization=cfg.sacrebleu_char_level, + ) + + def add_string(self, ref, pred): + self.ref.append(self.tokenizer.tokenize(ref)) + self.pred.append(self.tokenizer.tokenize(pred)) + + def _score(self, order=4): + if order != 4: + raise NotImplementedError + # tokenization and lowercasing are performed by self.tokenizer instead. + return self.sacrebleu.corpus_bleu(self.pred, [self.ref], tokenize="none") + + def score(self, order=4): + return self._score(order).score + + def result_string(self, order=4): + return self._score(order).format() + + +@dataclass +class BleuConfig(FairseqDataclass): + pad: int = field(default=1, metadata={"help": "padding index"}) + eos: int = field(default=2, metadata={"help": "eos index"}) + unk: int = field(default=3, metadata={"help": "unk index"}) + + +@register_scorer("bleu", dataclass=BleuConfig) +class Scorer(object): + def __init__(self, cfg): + self.stat = BleuStat() + self.pad = cfg.pad + self.eos = cfg.eos + self.unk = cfg.unk + + try: + from fairseq import libbleu + except ImportError as e: + sys.stderr.write( + "ERROR: missing libbleu.so. run `pip install --editable .`\n" + ) + raise e + + self.C = ctypes.cdll.LoadLibrary(libbleu.__file__) + + self.reset() + + def reset(self, one_init=False): + if one_init: + self.C.bleu_one_init(ctypes.byref(self.stat)) + else: + self.C.bleu_zero_init(ctypes.byref(self.stat)) + + def add(self, ref, pred): + if not isinstance(ref, torch.IntTensor): + raise TypeError("ref must be a torch.IntTensor (got {})".format(type(ref))) + if not isinstance(pred, torch.IntTensor): + raise TypeError("pred must be a torch.IntTensor(got {})".format(type(pred))) + + # don't match unknown words + rref = ref.clone() + assert not rref.lt(0).any() + rref[rref.eq(self.unk)] = -999 + + rref = rref.contiguous().view(-1) + pred = pred.contiguous().view(-1) + + self.C.bleu_add( + ctypes.byref(self.stat), + ctypes.c_size_t(rref.size(0)), + ctypes.c_void_p(rref.data_ptr()), + ctypes.c_size_t(pred.size(0)), + ctypes.c_void_p(pred.data_ptr()), + ctypes.c_int(self.pad), + ctypes.c_int(self.eos), + ) + + def score(self, order=4): + psum = sum( + math.log(p) if p > 0 else float("-Inf") for p in self.precision()[:order] + ) + return self.brevity() * math.exp(psum / order) * 100 + + def precision(self): + def ratio(a, b): + return a / b if b > 0 else 0 + + return [ + ratio(self.stat.match1, self.stat.count1), + ratio(self.stat.match2, self.stat.count2), + ratio(self.stat.match3, self.stat.count3), + ratio(self.stat.match4, self.stat.count4), + ] + + def brevity(self): + r = self.stat.reflen / self.stat.predlen + return min(1, math.exp(1 - r)) + + def result_string(self, order=4): + assert order <= 4, "BLEU scores for order > 4 aren't supported" + fmt = "BLEU{} = {:2.2f}, {:2.1f}" + for _ in range(1, order): + fmt += "/{:2.1f}" + fmt += " (BP={:.3f}, ratio={:.3f}, syslen={}, reflen={})" + bleup = [p * 100 for p in self.precision()[:order]] + return fmt.format( + order, + self.score(order=order), + *bleup, + self.brevity(), + self.stat.predlen / self.stat.reflen, + self.stat.predlen, + self.stat.reflen + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/scoring/chrf.py b/PyTorch/NLP/new-Transformer/fairseq/scoring/chrf.py new file mode 100644 index 00000000..5df5a1c0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/scoring/chrf.py @@ -0,0 +1,36 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + + +from dataclasses import dataclass + +from fairseq.dataclass import FairseqDataclass +from fairseq.scoring import BaseScorer, register_scorer + + +@dataclass +class ChrFScorerConfig(FairseqDataclass): + pass + + +@register_scorer("chrf", dataclass=ChrFScorerConfig) +class ChrFScorer(BaseScorer): + def __init__(self, args): + super(ChrFScorer, self).__init__(args) + import sacrebleu + + self.sacrebleu = sacrebleu + + def add_string(self, ref, pred): + self.ref.append(ref) + self.pred.append(pred) + + def score(self, order=4): + return self.result_string(order).score + + def result_string(self, order=4): + if order != 4: + raise NotImplementedError + return self.sacrebleu.corpus_chrf(self.pred, [self.ref]).format() diff --git a/PyTorch/NLP/new-Transformer/fairseq/scoring/meteor.py b/PyTorch/NLP/new-Transformer/fairseq/scoring/meteor.py new file mode 100644 index 00000000..32719956 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/scoring/meteor.py @@ -0,0 +1,42 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import numpy as np +from dataclasses import dataclass + +from fairseq.dataclass import FairseqDataclass +from fairseq.scoring import BaseScorer, register_scorer + + +@dataclass +class MeteorScorerConfig(FairseqDataclass): + pass + + +@register_scorer("meteor", dataclass=MeteorScorerConfig) +class MeteorScorer(BaseScorer): + def __init__(self, args): + super(MeteorScorer, self).__init__(args) + try: + import nltk + except ImportError: + raise ImportError("Please install nltk to use METEOR scorer") + + self.nltk = nltk + self.scores = [] + + def add_string(self, ref, pred): + self.ref.append(ref) + self.pred.append(pred) + + def score(self, order=4): + self.scores = [ + self.nltk.translate.meteor_score.single_meteor_score(r, p) + for r, p in zip(self.ref, self.pred) + ] + return np.mean(self.scores) + + def result_string(self, order=4): + return f"METEOR: {self.score():.4f}" diff --git a/PyTorch/NLP/new-Transformer/fairseq/scoring/tokenizer.py b/PyTorch/NLP/new-Transformer/fairseq/scoring/tokenizer.py new file mode 100644 index 00000000..b0cedd50 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/scoring/tokenizer.py @@ -0,0 +1,80 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import unicodedata + +import sacrebleu as sb + +from fairseq.dataclass import ChoiceEnum + +SACREBLEU_V2_ABOVE = int(sb.__version__[0]) >= 2 + + +class EvaluationTokenizer(object): + """A generic evaluation-time tokenizer, which leverages built-in tokenizers + in sacreBLEU (https://github.com/mjpost/sacrebleu). It additionally provides + lowercasing, punctuation removal and character tokenization, which are + applied after sacreBLEU tokenization. + + Args: + tokenizer_type (str): the type of sacreBLEU tokenizer to apply. + lowercase (bool): lowercase the text. + punctuation_removal (bool): remove punctuation (based on unicode + category) from text. + character_tokenization (bool): tokenize the text to characters. + """ + + SPACE = chr(32) + SPACE_ESCAPE = chr(9601) + _ALL_TOKENIZER_TYPES = ( + sb.BLEU.TOKENIZERS + if SACREBLEU_V2_ABOVE + else ["none", "13a", "intl", "zh", "ja-mecab"] + ) + ALL_TOKENIZER_TYPES = ChoiceEnum(_ALL_TOKENIZER_TYPES) + + def __init__( + self, + tokenizer_type: str = "13a", + lowercase: bool = False, + punctuation_removal: bool = False, + character_tokenization: bool = False, + ): + + assert ( + tokenizer_type in self._ALL_TOKENIZER_TYPES + ), f"{tokenizer_type}, {self._ALL_TOKENIZER_TYPES}" + self.lowercase = lowercase + self.punctuation_removal = punctuation_removal + self.character_tokenization = character_tokenization + if SACREBLEU_V2_ABOVE: + self.tokenizer = sb.BLEU(tokenize=str(tokenizer_type)).tokenizer + else: + self.tokenizer = sb.tokenizers.TOKENIZERS[tokenizer_type]() + + @classmethod + def remove_punctuation(cls, sent: str): + """Remove punctuation based on Unicode category.""" + return cls.SPACE.join( + t + for t in sent.split(cls.SPACE) + if not all(unicodedata.category(c)[0] == "P" for c in t) + ) + + def tokenize(self, sent: str): + tokenized = self.tokenizer(sent) + + if self.punctuation_removal: + tokenized = self.remove_punctuation(tokenized) + + if self.character_tokenization: + tokenized = self.SPACE.join( + list(tokenized.replace(self.SPACE, self.SPACE_ESCAPE)) + ) + + if self.lowercase: + tokenized = tokenized.lower() + + return tokenized diff --git a/PyTorch/NLP/new-Transformer/fairseq/scoring/wer.py b/PyTorch/NLP/new-Transformer/fairseq/scoring/wer.py new file mode 100644 index 00000000..633dc47c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/scoring/wer.py @@ -0,0 +1,58 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field + +from fairseq.dataclass import FairseqDataclass +from fairseq.scoring import BaseScorer, register_scorer +from fairseq.scoring.tokenizer import EvaluationTokenizer + + +@dataclass +class WerScorerConfig(FairseqDataclass): + wer_tokenizer: EvaluationTokenizer.ALL_TOKENIZER_TYPES = field( + default="none", metadata={"help": "sacreBLEU tokenizer to use for evaluation"} + ) + wer_remove_punct: bool = field( + default=False, metadata={"help": "remove punctuation"} + ) + wer_char_level: bool = field( + default=False, metadata={"help": "evaluate at character level"} + ) + wer_lowercase: bool = field(default=False, metadata={"help": "lowercasing"}) + + +@register_scorer("wer", dataclass=WerScorerConfig) +class WerScorer(BaseScorer): + def __init__(self, cfg): + super().__init__(cfg) + self.reset() + try: + import editdistance as ed + except ImportError: + raise ImportError("Please install editdistance to use WER scorer") + self.ed = ed + self.tokenizer = EvaluationTokenizer( + tokenizer_type=self.cfg.wer_tokenizer, + lowercase=self.cfg.wer_lowercase, + punctuation_removal=self.cfg.wer_remove_punct, + character_tokenization=self.cfg.wer_char_level, + ) + + def reset(self): + self.distance = 0 + self.ref_length = 0 + + def add_string(self, ref, pred): + ref_items = self.tokenizer.tokenize(ref).split() + pred_items = self.tokenizer.tokenize(pred).split() + self.distance += self.ed.eval(ref_items, pred_items) + self.ref_length += len(ref_items) + + def result_string(self): + return f"WER: {self.score():.2f}" + + def score(self): + return 100.0 * self.distance / self.ref_length if self.ref_length > 0 else 0 diff --git a/PyTorch/NLP/new-Transformer/fairseq/search.py b/PyTorch/NLP/new-Transformer/fairseq/search.py new file mode 100644 index 00000000..a71e7801 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/search.py @@ -0,0 +1,814 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +from typing import List, Optional + +import torch +import torch.nn as nn +from fairseq.token_generation_constraints import ( + ConstraintState, + OrderedConstraintState, + UnorderedConstraintState, +) +from torch import Tensor + + +class Search(nn.Module): + def __init__(self, tgt_dict): + super().__init__() + self.pad = tgt_dict.pad() + self.unk = tgt_dict.unk() + self.eos = tgt_dict.eos() + self.vocab_size = len(tgt_dict) + self.src_lengths = torch.tensor(-1) + self.supports_constraints = False + self.stop_on_max_len = False + + def step( + self, step, lprobs, scores, prev_output_tokens=None, original_batch_idxs=None + ): + """Take a single search step. + + Args: + step: the current search step, starting at 0 + lprobs: (bsz x input_beam_size x vocab_size) + the model's log-probabilities over the vocabulary at the current step + scores: (bsz x input_beam_size x step) + the historical model scores of each hypothesis up to this point + prev_output_tokens: (bsz x step) + the previously generated oputput tokens + original_batch_idxs: (bsz) + the tensor with the batch indices, in the range [0, bsz) + this is useful in case there has been applied a re-ordering + and we need to know the orignal indices + + Return: A tuple of (scores, indices, beams) where: + scores: (bsz x output_beam_size) + the scores of the chosen elements; output_beam_size can be + larger than input_beam_size, e.g., we may return + 2*input_beam_size to account for EOS + indices: (bsz x output_beam_size) + the indices of the chosen elements + beams: (bsz x output_beam_size) + the hypothesis ids of the chosen elements, in the range [0, input_beam_size) + """ + raise NotImplementedError + + @torch.jit.export + def set_src_lengths(self, src_lengths): + self.src_lengths = src_lengths + + @torch.jit.export + def init_constraints(self, batch_constraints: Optional[Tensor], beam_size: int): + """Initialize constraint states for constrained decoding (if supported). + + Args: + batch_constraints: (torch.Tensor, optional) + the list of constraints, in packed form + beam_size: (int) + the beam size + Returns: + *encoder_out* rearranged according to *new_order* + """ + pass + + def prune_sentences(self, batch_idxs: Tensor): + """ + Removes constraint states for completed sentences (if supported). + This is called from sequence_generator._generate() when sentences are + deleted from the batch. + + Args: + batch_idxs: Indices of *sentences* whose constraint state should be *kept*. + """ + pass + + def update_constraints(self, active_hypos: Tensor): + """ + Updates the constraint states by selecting the beam items that are retained. + This is called at each time step of sequence_generator._generate() when + the set of 2 * {beam_size} candidate hypotheses are reduced to the beam size. + + Args: + active_hypos: (batch size, beam size) + list of integers denoting, for each sentence, which beam candidate items + should be kept. + """ + pass + + +class BeamSearch(Search): + def __init__(self, tgt_dict): + super().__init__(tgt_dict) + self.constraint_states = None + + @torch.jit.export + def step( + self, + step: int, + lprobs, + scores: Optional[Tensor], + prev_output_tokens: Optional[Tensor] = None, + original_batch_idxs: Optional[Tensor] = None, + ): + bsz, beam_size, vocab_size = lprobs.size() + + if step == 0: + # at the first step all hypotheses are equally likely, so use + # only the first beam + lprobs = lprobs[:, ::beam_size, :].contiguous() + else: + # make probs contain cumulative scores for each hypothesis + assert scores is not None + lprobs = lprobs + scores[:, :, step - 1].unsqueeze(-1) + + top_prediction = torch.topk( + lprobs.view(bsz, -1), + k=min( + # Take the best 2 x beam_size predictions. We'll choose the first + # beam_size of these which don't predict eos to continue with. + beam_size * 2, + lprobs.view(bsz, -1).size(1) - 1, # -1 so we never select pad + ), + ) + scores_buf = top_prediction[0] + indices_buf = top_prediction[1] + # Project back into relative indices and beams + beams_buf = torch.div(indices_buf, vocab_size, rounding_mode="trunc") + indices_buf = indices_buf.fmod(vocab_size) + + # At this point, beams_buf and indices_buf are single-dim and contain relative indices + return scores_buf, indices_buf, beams_buf + + +class PrefixConstrainedBeamSearch(Search): + def __init__(self, tgt_dict, prefix_allowed_tokens_fn): + super().__init__(tgt_dict) + self.prefix_allowed_tokens_fn = prefix_allowed_tokens_fn + self.stop_on_max_len = True + + @torch.jit.export + def apply_mask(self, x, prev_output_tokens, original_batch_idxs): + beam_size = x.shape[0] // original_batch_idxs.shape[0] + original_batch_idxs = ( + original_batch_idxs.unsqueeze(-1).repeat((1, beam_size)).flatten().tolist() + ) + + mask = torch.full_like(x, -math.inf) + for sent_i, (sent, batch_i) in enumerate( + zip(prev_output_tokens, original_batch_idxs) + ): + mask[sent_i, :, self.prefix_allowed_tokens_fn(batch_i, sent)] = 0 + + return mask + + @torch.jit.export + def step( + self, + step: int, + lprobs: Tensor, + scores: Tensor, + prev_output_tokens: Tensor, + original_batch_idxs: Tensor, + ): + bsz, beam_size, vocab_size = lprobs.size() + + lprobs += self.apply_mask( + lprobs.view(bsz * beam_size, 1, vocab_size), + prev_output_tokens, + original_batch_idxs, + ).view(bsz, beam_size, vocab_size) + + if step == 0: + # at the first step all hypotheses are equally likely, so use + # only the first beam + lprobs = lprobs[:, ::beam_size, :].contiguous() + else: + # make probs contain cumulative scores for each hypothesis + assert scores is not None + lprobs = lprobs + scores[:, :, step - 1].unsqueeze(-1) + + top_prediction = torch.topk( + lprobs.view(bsz, -1), + k=min( + # Take the best beam_size predictions. We'll choose the first + # beam_size of these which don't predict eos to continue with. + beam_size, + lprobs.view(bsz, -1).size(1) - 1, # -1 so we never select pad + ), + ) + scores_buf = top_prediction[0] + indices_buf = top_prediction[1] + beams_buf = indices_buf // vocab_size + indices_buf = indices_buf.fmod(vocab_size) + return scores_buf, indices_buf, beams_buf + + +class LexicallyConstrainedBeamSearch(Search): + """Implements lexically constrained beam search as described in + + Fast Lexically Constrained Decoding with Dynamic Beam + Allocation for Neural Machine Translation. Post & Vilar, + NAACL 2018. https://www.aclweb.org/anthology/N18-1119/ + + and + + Improved Lexically Constrained Decoding for Translation and + Monolingual Rewriting. Hu et al, NAACL + 2019. https://www.aclweb.org/anthology/N19-1090/ + + This is accomplished by maintaining, for each beam hypothesis, a + ConstraintState object (see constraints.py) that tracks which + constraints have been generated and using this information to + shape the beam for each input sentence. + """ + + def __init__(self, tgt_dict, representation): + super().__init__(tgt_dict) + self.representation = representation + self.vocab_size = len(tgt_dict) + self.num_cands = 0 + self.supports_constraints = True + + @torch.jit.export + def init_constraints(self, batch_constraints: Optional[Tensor], beam_size: int): + self.constraint_states = [] + for constraint_tensor in batch_constraints: + if self.representation == "ordered": + constraint_state = OrderedConstraintState.create(constraint_tensor) + elif self.representation == "unordered": + constraint_state = UnorderedConstraintState.create(constraint_tensor) + + self.constraint_states.append([constraint_state for i in range(beam_size)]) + + @torch.jit.export + def prune_sentences(self, batch_idxs: Tensor): + self.constraint_states = [ + self.constraint_states[i] for i in batch_idxs.tolist() + ] + + @torch.jit.export + def update_constraints(self, active_hypos: Tensor): + if self.constraint_states: + batch_size = active_hypos.size(0) + for sentid in range(batch_size): + self.constraint_states[sentid] = [ + self.constraint_states[sentid][i] for i in active_hypos[sentid] + ] + + @torch.jit.export + def step( + self, + step: int, + lprobs: Tensor, + scores: Optional[Tensor], + prev_output_tokens: Optional[Tensor] = None, + original_batch_idxs: Optional[Tensor] = None, + ): + """ + A constrained step builds a large candidates list from the following: + - the top 2 * {beam_size} items over the whole beam + - for each item in the beam + - the top {each_k} (default 1) + - all next constraints + We then compute the constrained state of each beam item, and assign + stripe codes: 0 to the best in each bank, 1 to the 2nd-best, and so + on. We then sort by (stripe, score), and truncate the list at + 2 * beam size. + + Args: + step: the decoder step + lprobs: (batch size, beam size, target vocab) + the target-vocab distributions for each item in the beam. + Retrun: A tuple of (scores, indices, beams, constraints) where: + scores: (batch, output beam size) + the scores of the chosen elements + indices: (batch, output beam size) + the target vocab indices of the chosen elements + beams: (batch, output beam size) + the 0-indexed hypothesis ids of the chosen elements + constraints: (batch, output beam size) + the new constraint states + """ + each_k = 1 + device = lprobs.device + + batch_size, beam_size, vocab_size = lprobs.size() + + self.num_cands = min( + # Just take the k-best. We'll get another k from the 1-best from each + # row, plus more from the constraints + beam_size * 2, + lprobs.view(batch_size, -1).size(1) - 1, # -1 so we never select pad + ) + + # STEP 0: Preliminary. Prevent EOS for unfinished hyps across all batch items + constraint_states = self.constraint_states + if constraint_states and step > 0: + not_finished_indices = [] + for sentno, sent_constraints in enumerate(constraint_states): + for beamno, state in enumerate(sent_constraints): + index = sentno * beam_size + beamno + if not state.finished: + not_finished_indices.append(index) + not_finished_indices = torch.tensor(not_finished_indices) + if not_finished_indices.numel() > 0: + lprobs.view(batch_size * beam_size, -1)[ + not_finished_indices, self.eos + ] = -math.inf + + if step == 0: + # at the first step all hypotheses are equally likely, so use + # only the first beam entry for each batch item + lprobs = lprobs[:, ::beam_size, :].contiguous() + else: + # make probs contain cumulative scores for each hypothesis + assert scores is not None + lprobs = lprobs + scores[:, :, step - 1].unsqueeze(-1) + + top_prediction = torch.topk( + lprobs.view(batch_size, -1), + self.num_cands, + ) + scores_buf, indices_buf = top_prediction + # Project back into relative indices and beams + beams_buf = indices_buf // vocab_size + indices_buf = indices_buf.fmod(vocab_size) + + # Short circuit if there are no constraints in this batch + if not constraint_states: + return scores_buf, indices_buf, beams_buf + + # STEP 1: get top-1 from each hypothesis across all sentences in the batch + if step > 0: + top_scores, top_indices = torch.topk( + lprobs.view(batch_size * beam_size, -1), + k=each_k, + dim=1, + ) + top_scores = top_scores.view(batch_size, -1) + top_indices = top_indices.view(batch_size, -1) + scores_buf = torch.cat((scores_buf, top_scores), dim=1) + indices_buf = torch.cat((indices_buf, top_indices), dim=1) + new_beams = torch.arange(0, beam_size, device=device).repeat(batch_size, 1) + beams_buf = torch.cat((beams_buf, new_beams), dim=1) + + # Now, process sentences in the batch one by one. + new_scores_buf = torch.zeros((batch_size, 2 * beam_size), device=device) + new_indices_buf = torch.zeros((batch_size, 2 * beam_size), device=device).long() + new_beams_buf = torch.zeros((batch_size, 2 * beam_size), device=device).long() + for sentno, states in enumerate(constraint_states): + scores, indices, beams, new_states = self.step_sentence( + step, + sentno, + lprobs[sentno], + constraint_states[sentno], + beams_buf[sentno].clone(), + indices_buf[sentno].clone(), + scores_buf[sentno].clone(), + ) + new_scores_buf[sentno] = scores + new_indices_buf[sentno] = indices + new_beams_buf[sentno] = beams + self.constraint_states[sentno] = new_states + + return new_scores_buf, new_indices_buf, new_beams_buf + + @torch.jit.export + def step_sentence( + self, + step: int, + sentno: int, + lprobs: Tensor, + constraint_states: List[List[ConstraintState]], + beams_buf: Tensor, + indices_buf: Tensor, + scores_buf: Tensor, + ): + """Does per-sentence processing. Adds all constraints for each + hypothesis to the list of candidates; then removes duplicates, + sorts, and dynamically stripes across the banks. All tensor inputs + are collapsed to those pertaining to a single input sentence. + """ + device = lprobs.device + + # STEP 2: Add all constraints for each beam item + for beamno, state in enumerate(constraint_states): + next_tokens = torch.tensor(list(state.next_tokens()), device=device).long() + if next_tokens.numel() != 0: + indices_buf = torch.cat((indices_buf, next_tokens)) + next_beams = ( + torch.tensor(beamno, device=device) + .repeat(next_tokens.size(0)) + .long() + ) + beams_buf = torch.cat((beams_buf, next_beams)) + next_values = lprobs[beamno].take(next_tokens.view(-1)) + scores_buf = torch.cat((scores_buf, next_values)) + + # At the 0th time step, there is just one beam item + if step == 0: + break + + # STEP 3: Compute the "bank" for each candidate. This is the + # number of constraints it's generated. We need this so that + # we can do round-robin allocation of the beam across these + # banks. If C is the number of constraints, we select the best + # item in bank C, then the best in bank C-1, etc, followed by + # the 2nd-best in bank C, the 2nd-best in bank C-1, etc, and so + # on, until the maximum beam size. We accomplish this by + # creating a sort key and striping across the banks. + + # Compute the new states for all candidates + cands_size = indices_buf.size(0) + constraint_states = [ + constraint_states[beams_buf[i]].advance(indices_buf[i]) + for i in range(cands_size) + ] + + banks = torch.tensor([state.bank for state in constraint_states], device=device) + + # STEP 4: Sort + num_constraint_tokens = len(state.tokens) + + # Sort by keys (bank, score) (i.e., sort banks together, and scores + # within banks). AFAIK pytorch doesn't support either stable sort or + # multi-key sorting, so we have to hack this. + MAX_SCORE = -100 + sort_key = (num_constraint_tokens - banks) * MAX_SCORE + scores_buf + sort_values, sort_indices = sort_key.sort(dim=0, descending=True) + scores_buf = scores_buf[sort_indices] + indices_buf = indices_buf[sort_indices] + beams_buf = beams_buf[sort_indices] + banks = banks[sort_indices] + + # Sort the constraints to follow suit + constraint_states = [constraint_states[i] for i in sort_indices] + + # STEP 5: Remove duplicates. The topk calls (overall and + # per-row) plus the per-row generation of constraints will + # produce duplicates. Here we remove them. + + def roll(t): + """Rolls a 1d tensor left by 1. + + [0, 1, 2, 3, 4] becomes [4, 0, 1, 2, 3] + """ + return torch.cat((t[-1].unsqueeze(0), t[0:-1]), dim=0) + + # We map candidates (beam, token_id) to a single dimension. + # This is then shifted by 1. We can then easily identify + # duplicates and create a mask that identifies unique + # extensions. + uniques_mask = beams_buf * (self.vocab_size + 1) + indices_buf + uniques_mask = roll(uniques_mask) != uniques_mask + + # Use the mask to pare down the data structures + scores_buf = torch.masked_select(scores_buf, uniques_mask) + indices_buf = torch.masked_select(indices_buf, uniques_mask) + beams_buf = torch.masked_select(beams_buf, uniques_mask) + banks = torch.masked_select(banks, uniques_mask) + i = 1 + for mask in uniques_mask[1:]: + if not mask: + constraint_states.pop(i) + i += mask + + # STEP 6: Assign IDs round-robin across banks, sort, and + # truncate. Now that the candidates are sorted by (bank, + # score) and uniqed, we dynamically allocate the {beam_size} + # beam by striping across the candidates. These stripes will + # be used as sort keys to do round-robin selection. This is + # accomplished in a single pass with offsets. Sorting by + # highest-banks (furthest-along hypotheses) first ensures + # progress through the constraints. + # + # e.g., BANKS: 3 3 3 2 2 2 2 1 1 1 0 0 + # OLD STRIPES: 0 1 2 0 1 2 3 0 1 2 0 1 + # NEW STRIPES: 0 1+4 2+8 0+1 1+5 2+9 3+11 0+2 1+6 2+10 0+3 1+7 + # = 0 5 10 1 6 11 13 2 7 12 3 8 + # + # Sorting by this then gives the following banks: + # + # 3 2 1 0 3 2 1 0 3 2 1 2 + # + # We'll take the top {beam_size} of these. + stripe_offsets = [offset * (len(banks) + 1) for offset in range(len(banks) + 1)] + stripes = torch.zeros_like(banks) + cur_bank_count = -1 + cur_bank = banks[0] + for i, bank in enumerate(banks): + if bank != cur_bank: + cur_bank_count = 0 + cur_bank = bank + else: + cur_bank_count += 1 + stripes[i] = num_constraint_tokens - bank + stripe_offsets[cur_bank_count] + + # STEP 7: Sort by the stripes values + sort_values, sort_indices = stripes.sort(dim=0) + scores_buf = scores_buf[sort_indices] + indices_buf = indices_buf[sort_indices] + beams_buf = beams_buf[sort_indices] + constraint_states = [constraint_states[i] for i in sort_indices] + + # STEP 8: Truncate to the candidates size! + scores_buf = scores_buf[: self.num_cands] + indices_buf = indices_buf[: self.num_cands] + beams_buf = beams_buf[: self.num_cands] + + return scores_buf, indices_buf, beams_buf, constraint_states + + +class LengthConstrainedBeamSearch(Search): + def __init__(self, tgt_dict, min_len_a, min_len_b, max_len_a, max_len_b): + super().__init__(tgt_dict) + self.min_len_a = min_len_a + self.min_len_b = min_len_b + self.max_len_a = max_len_a + self.max_len_b = max_len_b + self.beam = BeamSearch(tgt_dict) + self.needs_src_lengths = True + + def step( + self, + step: int, + lprobs, + scores, + prev_output_tokens: Optional[Tensor] = None, + original_batch_idxs: Optional[Tensor] = None, + ): + min_lens = self.min_len_a * self.src_lengths + self.min_len_b + max_lens = self.max_len_a * self.src_lengths + self.max_len_b + lprobs[step < min_lens, :, self.eos] = -math.inf + lprobs[step >= max_lens, :, self.eos] = 0 + return self.beam.step(step, lprobs, scores) + + +class DiverseBeamSearch(Search): + """Diverse Beam Search. + + See "Diverse Beam Search: Decoding Diverse Solutions from Neural Sequence + Models" for details. + + We only implement the Hamming Diversity penalty here, which performed best + in the original paper. + """ + + def __init__(self, tgt_dict, num_groups, diversity_strength): + super().__init__(tgt_dict) + self.num_groups = num_groups + self.diversity_strength = -diversity_strength + self.beam = BeamSearch(tgt_dict) + + @torch.jit.export + def step( + self, + step: int, + lprobs, + scores, + prev_output_tokens: Optional[Tensor] = None, + original_batch_idxs: Optional[Tensor] = None, + ): + bsz, beam_size, vocab_size = lprobs.size() + if beam_size % self.num_groups != 0: + raise ValueError( + "DiverseBeamSearch requires --beam to be divisible by the number of groups" + ) + + # initialize diversity penalty + diversity_buf = torch.zeros(lprobs[:, 0, :].size()).to(lprobs) + + scores_G, indices_G, beams_G = [], [], [] + for g in range(self.num_groups): + lprobs_g = lprobs[:, g :: self.num_groups, :] + scores_g = scores[:, g :: self.num_groups, :] if step > 0 else None + + # apply diversity penalty + if g > 0: + lprobs_g = torch.add( + lprobs_g, + other=diversity_buf.unsqueeze(1), + alpha=self.diversity_strength, + ) + else: + lprobs_g = lprobs_g.contiguous() + + scores_buf, indices_buf, beams_buf = self.beam.step( + step, lprobs_g, scores_g + ) + beams_buf.mul_(self.num_groups).add_(g) + + scores_G.append(scores_buf.clone()) + indices_G.append(indices_buf.clone()) + beams_G.append(beams_buf.clone()) + + # update diversity penalty + diversity_buf.scatter_add_( + 1, indices_buf, torch.ones(indices_buf.size()).to(diversity_buf) + ) + + # interleave results from different groups + scores_buf = torch.stack(scores_G, dim=2).view(bsz, -1) + indices_buf = torch.stack(indices_G, dim=2).view(bsz, -1) + beams_buf = torch.stack(beams_G, dim=2).view(bsz, -1) + return scores_buf, indices_buf, beams_buf + + +class Sampling(Search): + sampling_topk: int + sampling_topp: float + + def __init__(self, tgt_dict, sampling_topk=-1, sampling_topp=-1.0): + super().__init__(tgt_dict) + self.sampling_topk = sampling_topk + self.sampling_topp = sampling_topp + + def _sample_topp(self, lprobs): + """Sample among the smallest set of elements whose cumulative probability mass exceeds p. + + See `"The Curious Case of Neural Text Degeneration" + (Holtzman et al., 2019) `_. + + Args: + lprobs: (bsz x input_beam_size x vocab_size) + the model's log-probabilities over the vocabulary at the current step + + Return: A tuple of (trimed_probs, truncated_indices) where: + trimed_probs: (bsz x input_beam_size x ?) + the model's probabilities over the elements selected to sample from. The + width of the third dimension is determined by top-P. + truncated_indices: (bsz x input_beam_size x ?) + the indices of the chosen elements. + """ + probs = lprobs.exp_() + + # sort the last dimension (vocab dimension) in descending order + sorted_probs, sorted_indices = probs.sort(descending=True) + + # compute a mask to indicate the words to be included in the top-P set. + cumsum_probs = sorted_probs.cumsum(dim=2) + mask = cumsum_probs.lt(self.sampling_topp) + + # note that mask was computed by 'lt'. One more word needs to be included + # so that the cumulative probability mass can exceed p. + cumsum_mask = mask.cumsum(dim=2) + last_included = cumsum_mask[:, :, -1:] + last_included.clamp_(0, mask.size()[2] - 1) + mask = mask.scatter_(2, last_included, 1) + + # truncate unnecessary dims. + max_dim = last_included.max() + truncated_mask = mask[:, :, : max_dim + 1] + truncated_probs = sorted_probs[:, :, : max_dim + 1] + truncated_indices = sorted_indices[:, :, : max_dim + 1] + + # trim the words that are not in top-P by setting their probabilities + # to 0, so that they would not be sampled later. + trim_mask = ~truncated_mask + trimed_probs = truncated_probs.masked_fill_(trim_mask, 0) + return trimed_probs, truncated_indices + + @torch.jit.export + def step( + self, + step: int, + lprobs, + scores, + prev_output_tokens: Optional[Tensor] = None, + original_batch_idxs: Optional[Tensor] = None, + ): + bsz, beam_size, vocab_size = lprobs.size() + + if step == 0: + # at the first step all hypotheses are equally likely, so use + # only the first beam + lprobs = lprobs[:, ::beam_size, :].contiguous() + + if self.sampling_topp > 0: + # only sample from the smallest set of words whose cumulative probability mass exceeds p + probs, top_indices = self._sample_topp(lprobs) + elif self.sampling_topk > 0: + # only sample from top-k candidates + lprobs, top_indices = lprobs.topk(self.sampling_topk) + probs = lprobs.exp_() + else: + probs = lprobs.exp_() + + # dummy data to be consistent with true branch for type check + top_indices = torch.empty(0).to(probs) + # sample + if step == 0: + indices_buf = torch.multinomial( + probs.view(bsz, -1), + beam_size, + replacement=True, + ).view(bsz, beam_size) + else: + indices_buf = torch.multinomial( + probs.view(bsz * beam_size, -1), + 1, + replacement=True, + ).view(bsz, beam_size) + + if step == 0: + # expand to beam size + probs = probs.expand(bsz, beam_size, -1) + + # gather scores + scores_buf = torch.gather(probs, dim=2, index=indices_buf.unsqueeze(-1)) + scores_buf = scores_buf.log_().view(bsz, -1) + + # remap indices if using top-k or top-P sampling + if self.sampling_topk > 0 or self.sampling_topp > 0: + indices_buf = torch.gather( + top_indices.expand(bsz, beam_size, -1), + dim=2, + index=indices_buf.unsqueeze(-1), + ).squeeze(2) + + if step == 0: + beams_buf = indices_buf.new_zeros(bsz, beam_size) + else: + beams_buf = torch.arange(0, beam_size).to(indices_buf).repeat(bsz, 1) + # make scores cumulative + scores_buf.add_( + torch.gather(scores[:, :, step - 1], dim=1, index=beams_buf) + ) + + return scores_buf, indices_buf, beams_buf + + +class DiverseSiblingsSearch(Search): + """ + Beam search with diverse siblings. + + See "A Simple, Fast Diverse Decoding Algorithm for Neural Generation" for details. + https://arxiv.org/abs/1611.08562 + + 1/ Calculate hypotheses for each beam + 2/ Intra-sibling ordering + 3/ Rewrite scores + 4/ Choose top K hypotheses + + if diversity_rate == 0 is equivalent to BeamSearch + """ + + def __init__(self, tgt_dict, diversity_rate): + super().__init__(tgt_dict) + self.diversity_rate = diversity_rate + self.beam = BeamSearch(tgt_dict) + + def step( + self, + step: int, + lprobs, + scores, + prev_output_tokens: Optional[Tensor] = None, + original_batch_idxs: Optional[Tensor] = None, + ): + bsz, beam_size, vocab_size = lprobs.size() + k = min( + # Take the best 2 x beam_size predictions. We'll choose the first + # beam_size of these which don't predict eos to continue with. + beam_size * 2, + lprobs.view(bsz, -1).size(1) - 1, # -1 so we never select pad + ) + s_list: List[Tensor] + i_list: List[Tensor] + s_list = [torch.empty(0).to(lprobs) for i in range(beam_size)] + i_list = [torch.LongTensor().to(device=lprobs.device) for i in range(beam_size)] + sibling_score = torch.arange(1, k + 1).to(lprobs) * self.diversity_rate + + if step == 0: + return self.beam.step(step, lprobs, scores) + lprobs.add_(scores[:, :, step - 1].unsqueeze(-1)) + + # 1/ Calculate hypotheses for each beam + for i in range(beam_size): + torch.topk(lprobs[:, i, :].view(bsz, -1), k, out=(s_list[i], i_list[i])) + i_list[i].fmod_(vocab_size) + + # 2/ Intra-sibling ordering by default from topk + 3/ Rewrite scores + s_list[i].sub_(sibling_score) + + # 4/ Choose top K hypotheses + indices = torch.stack(i_list, dim=1).view(bsz, -1) + + final_scores = torch.empty(0).to(lprobs) + final_indices = torch.LongTensor().to(device=lprobs.device) + final_beams = torch.LongTensor().to(device=lprobs.device) + (final_scores, final_indices) = torch.topk( + torch.stack(s_list, dim=1).view(bsz, -1), + k, + ) + + final_beams = final_indices // k + + for i in range(bsz): + final_indices[i] = indices[i][final_indices[i]] + + return final_scores, final_indices, final_beams diff --git a/PyTorch/NLP/new-Transformer/fairseq/sequence_generator.py b/PyTorch/NLP/new-Transformer/fairseq/sequence_generator.py new file mode 100644 index 00000000..7d323d85 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/sequence_generator.py @@ -0,0 +1,997 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import math +import sys +from typing import Dict, List, Optional + +import torch +import torch.nn as nn +from torch import Tensor + +from fairseq import search, utils +from fairseq.data import data_utils +from fairseq.models import FairseqIncrementalDecoder +from fairseq.ngram_repeat_block import NGramRepeatBlock + + +class SequenceGenerator(nn.Module): + def __init__( + self, + models, + tgt_dict, + beam_size=1, + max_len_a=0, + max_len_b=200, + max_len=0, + min_len=1, + normalize_scores=True, + len_penalty=1.0, + unk_penalty=0.0, + temperature=1.0, + match_source_len=False, + no_repeat_ngram_size=0, + search_strategy=None, + eos=None, + symbols_to_strip_from_output=None, + lm_model=None, + lm_weight=1.0, + ): + """Generates translations of a given source sentence. + + Args: + models (List[~fairseq.models.FairseqModel]): ensemble of models, + currently support fairseq.models.TransformerModel for scripting + beam_size (int, optional): beam width (default: 1) + max_len_a/b (int, optional): generate sequences of maximum length + ax + b, where x is the source length + max_len (int, optional): the maximum length of the generated output + (not including end-of-sentence) + min_len (int, optional): the minimum length of the generated output + (not including end-of-sentence) + normalize_scores (bool, optional): normalize scores by the length + of the output (default: True) + len_penalty (float, optional): length penalty, where <1.0 favors + shorter, >1.0 favors longer sentences (default: 1.0) + unk_penalty (float, optional): unknown word penalty, where <0 + produces more unks, >0 produces fewer (default: 0.0) + temperature (float, optional): temperature, where values + >1.0 produce more uniform samples and values <1.0 produce + sharper samples (default: 1.0) + match_source_len (bool, optional): outputs should match the source + length (default: False) + """ + super().__init__() + if isinstance(models, EnsembleModel): + self.model = models + else: + self.model = EnsembleModel(models) + self.tgt_dict = tgt_dict + self.pad = tgt_dict.pad() + self.unk = tgt_dict.unk() + self.eos = tgt_dict.eos() if eos is None else eos + self.symbols_to_strip_from_output = ( + symbols_to_strip_from_output.union({self.eos}) + if symbols_to_strip_from_output is not None + else {self.eos} + ) + self.vocab_size = len(tgt_dict) + self.beam_size = beam_size + # the max beam size is the dictionary size - 1, since we never select pad + self.beam_size = min(beam_size, self.vocab_size - 1) + self.model.set_decoder_beam_size(self.beam_size) + self.max_len_a = max_len_a + self.max_len_b = max_len_b + self.min_len = min_len + self.max_len = max_len or self.model.max_decoder_positions() + + self.normalize_scores = normalize_scores + self.len_penalty = len_penalty + self.unk_penalty = unk_penalty + self.temperature = temperature + self.match_source_len = match_source_len + + if no_repeat_ngram_size > 0: + self.repeat_ngram_blocker = NGramRepeatBlock(no_repeat_ngram_size) + else: + self.repeat_ngram_blocker = None + + assert temperature > 0, "--temperature must be greater than 0" + + self.search = ( + search.BeamSearch(tgt_dict) if search_strategy is None else search_strategy + ) + # We only need to set src_lengths in LengthConstrainedBeamSearch. + # As a module attribute, setting it would break in multithread + # settings when the model is shared. + self.should_set_src_lengths = ( + hasattr(self.search, "needs_src_lengths") and self.search.needs_src_lengths + ) + + self.model.eval() + + self.lm_model = lm_model + self.lm_weight = lm_weight + if self.lm_model is not None: + self.lm_model.eval() + + def cuda(self): + self.model.cuda() + return self + + @torch.no_grad() + def forward( + self, + sample: Dict[str, Dict[str, Tensor]], + prefix_tokens: Optional[Tensor] = None, + bos_token: Optional[int] = None, + ): + """Generate a batch of translations. + + Args: + sample (dict): batch + prefix_tokens (torch.LongTensor, optional): force decoder to begin + with these tokens + bos_token (int, optional): beginning of sentence token + (default: self.eos) + """ + return self._generate(sample, prefix_tokens, bos_token=bos_token) + + # TODO(myleott): unused, deprecate after pytorch-translate migration + def generate_batched_itr(self, data_itr, beam_size=None, cuda=False, timer=None): + """Iterate over a batched dataset and yield individual translations. + Args: + cuda (bool, optional): use GPU for generation + timer (StopwatchMeter, optional): time generations + """ + for sample in data_itr: + s = utils.move_to_cuda(sample) if cuda else sample + if "net_input" not in s: + continue + input = s["net_input"] + # model.forward normally channels prev_output_tokens into the decoder + # separately, but SequenceGenerator directly calls model.encoder + encoder_input = { + k: v for k, v in input.items() if k != "prev_output_tokens" + } + if timer is not None: + timer.start() + with torch.no_grad(): + hypos = self.generate(encoder_input) + if timer is not None: + timer.stop(sum(len(h[0]["tokens"]) for h in hypos)) + for i, id in enumerate(s["id"].data): + # remove padding + src = utils.strip_pad(input["src_tokens"].data[i, :], self.pad) + ref = ( + utils.strip_pad(s["target"].data[i, :], self.pad) + if s["target"] is not None + else None + ) + yield id, src, ref, hypos[i] + + @torch.no_grad() + def generate( + self, models, sample: Dict[str, Dict[str, Tensor]], **kwargs + ) -> List[List[Dict[str, Tensor]]]: + """Generate translations. Match the api of other fairseq generators. + + Args: + models (List[~fairseq.models.FairseqModel]): ensemble of models + sample (dict): batch + prefix_tokens (torch.LongTensor, optional): force decoder to begin + with these tokens + constraints (torch.LongTensor, optional): force decoder to include + the list of constraints + bos_token (int, optional): beginning of sentence token + (default: self.eos) + """ + return self._generate(sample, **kwargs) + + def _generate( + self, + sample: Dict[str, Dict[str, Tensor]], + prefix_tokens: Optional[Tensor] = None, + constraints: Optional[Tensor] = None, + bos_token: Optional[int] = None, + ): + incremental_states = torch.jit.annotate( + List[Dict[str, Dict[str, Optional[Tensor]]]], + [ + torch.jit.annotate(Dict[str, Dict[str, Optional[Tensor]]], {}) + for i in range(self.model.models_size) + ], + ) + net_input = sample["net_input"] + + if "src_tokens" in net_input: + src_tokens = net_input["src_tokens"] + # length of the source text being the character length except EndOfSentence and pad + src_lengths = ( + (src_tokens.ne(self.eos) & src_tokens.ne(self.pad)).long().sum(dim=1) + ) + elif "source" in net_input: + src_tokens = net_input["source"] + src_lengths = ( + net_input["padding_mask"].size(-1) - net_input["padding_mask"].sum(-1) + if net_input["padding_mask"] is not None + else torch.tensor(src_tokens.size(-1)).to(src_tokens) + ) + elif "features" in net_input: + src_tokens = net_input["features"] + src_lengths = ( + net_input["padding_mask"].size(-1) - net_input["padding_mask"].sum(-1) + if net_input["padding_mask"] is not None + else torch.tensor(src_tokens.size(-1)).to(src_tokens) + ) + else: + raise Exception( + "expected src_tokens or source in net input. input keys: " + + str(net_input.keys()) + ) + + # bsz: total number of sentences in beam + # Note that src_tokens may have more than 2 dimensions (i.e. audio features) + bsz, src_len = src_tokens.size()[:2] + beam_size = self.beam_size + + if constraints is not None and not self.search.supports_constraints: + raise NotImplementedError( + "Target-side constraints were provided, but search method doesn't support them" + ) + + # Initialize constraints, when active + self.search.init_constraints(constraints, beam_size) + + max_len: int = -1 + if self.match_source_len: + max_len = src_lengths.max().item() + else: + max_len = min( + int(self.max_len_a * src_len + self.max_len_b), + self.max_len - 1, + ) + assert ( + self.min_len <= max_len + ), "min_len cannot be larger than max_len, please adjust these!" + # compute the encoder output for each beam + with torch.autograd.profiler.record_function("EnsembleModel: forward_encoder"): + encoder_outs = self.model.forward_encoder(net_input) + + # placeholder of indices for bsz * beam_size to hold tokens and accumulative scores + new_order = torch.arange(bsz).view(-1, 1).repeat(1, beam_size).view(-1) + new_order = new_order.to(src_tokens.device).long() + encoder_outs = self.model.reorder_encoder_out(encoder_outs, new_order) + # ensure encoder_outs is a List. + assert encoder_outs is not None + + # initialize buffers + scores = ( + torch.zeros(bsz * beam_size, max_len + 1).to(src_tokens).float() + ) # +1 for eos; pad is never chosen for scoring + tokens = ( + torch.zeros(bsz * beam_size, max_len + 2) + .to(src_tokens) + .long() + .fill_(self.pad) + ) # +2 for eos and pad + tokens[:, 0] = self.eos if bos_token is None else bos_token + attn: Optional[Tensor] = None + + # A list that indicates candidates that should be ignored. + # For example, suppose we're sampling and have already finalized 2/5 + # samples. Then cands_to_ignore would mark 2 positions as being ignored, + # so that we only finalize the remaining 3 samples. + cands_to_ignore = ( + torch.zeros(bsz, beam_size).to(src_tokens).eq(-1) + ) # forward and backward-compatible False mask + + # list of completed sentences + finalized = torch.jit.annotate( + List[List[Dict[str, Tensor]]], + [torch.jit.annotate(List[Dict[str, Tensor]], []) for i in range(bsz)], + ) # contains lists of dictionaries of infomation about the hypothesis being finalized at each step + + # a boolean array indicating if the sentence at the index is finished or not + finished = [False for i in range(bsz)] + num_remaining_sent = bsz # number of sentences remaining + + # number of candidate hypos per step + cand_size = 2 * beam_size # 2 x beam size in case half are EOS + + # offset arrays for converting between different indexing schemes + bbsz_offsets = ( + (torch.arange(0, bsz) * beam_size) + .unsqueeze(1) + .type_as(tokens) + .to(src_tokens.device) + ) + cand_offsets = torch.arange(0, cand_size).type_as(tokens).to(src_tokens.device) + + reorder_state: Optional[Tensor] = None + batch_idxs: Optional[Tensor] = None + + original_batch_idxs: Optional[Tensor] = None + if "id" in sample and isinstance(sample["id"], Tensor): + original_batch_idxs = sample["id"] + else: + original_batch_idxs = torch.arange(0, bsz).type_as(tokens) + + for step in range(max_len + 1): # one extra step for EOS marker + # reorder decoder internal states based on the prev choice of beams + if reorder_state is not None: + if batch_idxs is not None: + # update beam indices to take into account removed sentences + corr = batch_idxs - torch.arange(batch_idxs.numel()).type_as( + batch_idxs + ) + reorder_state.view(-1, beam_size).add_( + corr.unsqueeze(-1) * beam_size + ) + original_batch_idxs = original_batch_idxs[batch_idxs] + self.model.reorder_incremental_state(incremental_states, reorder_state) + encoder_outs = self.model.reorder_encoder_out( + encoder_outs, reorder_state + ) + with torch.autograd.profiler.record_function( + "EnsembleModel: forward_decoder" + ): + lprobs, avg_attn_scores = self.model.forward_decoder( + tokens[:, : step + 1], + encoder_outs, + incremental_states, + self.temperature, + ) + + if self.lm_model is not None: + lm_out = self.lm_model(tokens[:, : step + 1]) + probs = self.lm_model.get_normalized_probs( + lm_out, log_probs=True, sample=None + ) + probs = probs[:, -1, :] * self.lm_weight + lprobs += probs + + lprobs[lprobs != lprobs] = torch.tensor(-math.inf).to(lprobs) + + lprobs[:, self.pad] = -math.inf # never select pad + lprobs[:, self.unk] -= self.unk_penalty # apply unk penalty + + # handle max length constraint + if step >= max_len: + lprobs[:, : self.eos] = -math.inf + lprobs[:, self.eos + 1 :] = -math.inf + + # handle prefix tokens (possibly with different lengths) + if ( + prefix_tokens is not None + and step < prefix_tokens.size(1) + and step < max_len + ): + lprobs, tokens, scores = self._prefix_tokens( + step, lprobs, scores, tokens, prefix_tokens, beam_size + ) + elif step < self.min_len: + # minimum length constraint (does not apply if using prefix_tokens) + lprobs[:, self.eos] = -math.inf + + # Record attention scores, only support avg_attn_scores is a Tensor + if avg_attn_scores is not None: + if attn is None: + attn = torch.empty( + bsz * beam_size, avg_attn_scores.size(1), max_len + 2 + ).to(scores) + attn[:, :, step + 1].copy_(avg_attn_scores) + + scores = scores.type_as(lprobs) + eos_bbsz_idx = torch.empty(0).to( + tokens + ) # indices of hypothesis ending with eos (finished sentences) + eos_scores = torch.empty(0).to( + scores + ) # scores of hypothesis ending with eos (finished sentences) + + if self.should_set_src_lengths: + self.search.set_src_lengths(src_lengths) + + if self.repeat_ngram_blocker is not None: + lprobs = self.repeat_ngram_blocker(tokens, lprobs, bsz, beam_size, step) + + # Shape: (batch, cand_size) + cand_scores, cand_indices, cand_beams = self.search.step( + step, + lprobs.view(bsz, -1, self.vocab_size), + scores.view(bsz, beam_size, -1)[:, :, :step], + tokens[:, : step + 1], + original_batch_idxs, + ) + + # cand_bbsz_idx contains beam indices for the top candidate + # hypotheses, with a range of values: [0, bsz*beam_size), + # and dimensions: [bsz, cand_size] + cand_bbsz_idx = cand_beams.add(bbsz_offsets) + + # finalize hypotheses that end in eos + # Shape of eos_mask: (batch size, beam size) + eos_mask = cand_indices.eq(self.eos) & cand_scores.ne(-math.inf) + eos_mask[:, :beam_size][cands_to_ignore] = torch.tensor(0).to(eos_mask) + + # only consider eos when it's among the top beam_size indices + # Now we know what beam item(s) to finish + # Shape: 1d list of absolute-numbered + eos_bbsz_idx = torch.masked_select( + cand_bbsz_idx[:, :beam_size], mask=eos_mask[:, :beam_size] + ) + + finalized_sents: List[int] = [] + if eos_bbsz_idx.numel() > 0: + eos_scores = torch.masked_select( + cand_scores[:, :beam_size], mask=eos_mask[:, :beam_size] + ) + + finalized_sents = self.finalize_hypos( + step, + eos_bbsz_idx, + eos_scores, + tokens, + scores, + finalized, + finished, + beam_size, + attn, + src_lengths, + max_len, + ) + num_remaining_sent -= len(finalized_sents) + + assert num_remaining_sent >= 0 + if num_remaining_sent == 0: + break + if self.search.stop_on_max_len and step >= max_len: + break + assert step < max_len, f"{step} < {max_len}" + + # Remove finalized sentences (ones for which {beam_size} + # finished hypotheses have been generated) from the batch. + if len(finalized_sents) > 0: + new_bsz = bsz - len(finalized_sents) + + # construct batch_idxs which holds indices of batches to keep for the next pass + batch_mask = torch.ones( + bsz, dtype=torch.bool, device=cand_indices.device + ) + batch_mask[finalized_sents] = False + # TODO replace `nonzero(as_tuple=False)` after TorchScript supports it + batch_idxs = torch.arange( + bsz, device=cand_indices.device + ).masked_select(batch_mask) + + # Choose the subset of the hypothesized constraints that will continue + self.search.prune_sentences(batch_idxs) + + eos_mask = eos_mask[batch_idxs] + cand_beams = cand_beams[batch_idxs] + bbsz_offsets.resize_(new_bsz, 1) + cand_bbsz_idx = cand_beams.add(bbsz_offsets) + cand_scores = cand_scores[batch_idxs] + cand_indices = cand_indices[batch_idxs] + + if prefix_tokens is not None: + prefix_tokens = prefix_tokens[batch_idxs] + src_lengths = src_lengths[batch_idxs] + cands_to_ignore = cands_to_ignore[batch_idxs] + + scores = scores.view(bsz, -1)[batch_idxs].view(new_bsz * beam_size, -1) + tokens = tokens.view(bsz, -1)[batch_idxs].view(new_bsz * beam_size, -1) + if attn is not None: + attn = attn.view(bsz, -1)[batch_idxs].view( + new_bsz * beam_size, attn.size(1), -1 + ) + bsz = new_bsz + else: + batch_idxs = None + + # Set active_mask so that values > cand_size indicate eos hypos + # and values < cand_size indicate candidate active hypos. + # After, the min values per row are the top candidate active hypos + + # Rewrite the operator since the element wise or is not supported in torchscript. + + eos_mask[:, :beam_size] = ~((~cands_to_ignore) & (~eos_mask[:, :beam_size])) + active_mask = torch.add( + eos_mask.type_as(cand_offsets) * cand_size, + cand_offsets[: eos_mask.size(1)], + ) + + # get the top beam_size active hypotheses, which are just + # the hypos with the smallest values in active_mask. + # {active_hypos} indicates which {beam_size} hypotheses + # from the list of {2 * beam_size} candidates were + # selected. Shapes: (batch size, beam size) + new_cands_to_ignore, active_hypos = torch.topk( + active_mask, k=beam_size, dim=1, largest=False + ) + + # update cands_to_ignore to ignore any finalized hypos. + cands_to_ignore = new_cands_to_ignore.ge(cand_size)[:, :beam_size] + # Make sure there is at least one active item for each sentence in the batch. + assert (~cands_to_ignore).any(dim=1).all() + + # update cands_to_ignore to ignore any finalized hypos + + # {active_bbsz_idx} denotes which beam number is continued for each new hypothesis (a beam + # can be selected more than once). + active_bbsz_idx = torch.gather(cand_bbsz_idx, dim=1, index=active_hypos) + active_scores = torch.gather(cand_scores, dim=1, index=active_hypos) + + active_bbsz_idx = active_bbsz_idx.view(-1) + active_scores = active_scores.view(-1) + + # copy tokens and scores for active hypotheses + + # Set the tokens for each beam (can select the same row more than once) + tokens[:, : step + 1] = torch.index_select( + tokens[:, : step + 1], dim=0, index=active_bbsz_idx + ) + # Select the next token for each of them + tokens.view(bsz, beam_size, -1)[:, :, step + 1] = torch.gather( + cand_indices, dim=1, index=active_hypos + ) + if step > 0: + scores[:, :step] = torch.index_select( + scores[:, :step], dim=0, index=active_bbsz_idx + ) + scores.view(bsz, beam_size, -1)[:, :, step] = torch.gather( + cand_scores, dim=1, index=active_hypos + ) + + # Update constraints based on which candidates were selected for the next beam + self.search.update_constraints(active_hypos) + + # copy attention for active hypotheses + if attn is not None: + attn[:, :, : step + 2] = torch.index_select( + attn[:, :, : step + 2], dim=0, index=active_bbsz_idx + ) + + # reorder incremental state in decoder + reorder_state = active_bbsz_idx + + # sort by score descending + for sent in range(len(finalized)): + scores = torch.tensor( + [float(elem["score"].item()) for elem in finalized[sent]] + ) + _, sorted_scores_indices = torch.sort(scores, descending=True) + finalized[sent] = [finalized[sent][ssi] for ssi in sorted_scores_indices] + finalized[sent] = torch.jit.annotate( + List[Dict[str, Tensor]], finalized[sent] + ) + return finalized + + def _prefix_tokens( + self, step: int, lprobs, scores, tokens, prefix_tokens, beam_size: int + ): + """Handle prefix tokens""" + prefix_toks = prefix_tokens[:, step].unsqueeze(-1).repeat(1, beam_size).view(-1) + prefix_lprobs = lprobs.gather(-1, prefix_toks.unsqueeze(-1)) + prefix_mask = prefix_toks.ne(self.pad) + lprobs[prefix_mask] = torch.tensor(-math.inf).to(lprobs) + lprobs[prefix_mask] = lprobs[prefix_mask].scatter( + -1, prefix_toks[prefix_mask].unsqueeze(-1), prefix_lprobs[prefix_mask] + ) + # if prefix includes eos, then we should make sure tokens and + # scores are the same across all beams + eos_mask = prefix_toks.eq(self.eos) + if eos_mask.any(): + # validate that the first beam matches the prefix + first_beam = tokens[eos_mask].view(-1, beam_size, tokens.size(-1))[ + :, 0, 1 : step + 1 + ] + eos_mask_batch_dim = eos_mask.view(-1, beam_size)[:, 0] + target_prefix = prefix_tokens[eos_mask_batch_dim][:, :step] + assert (first_beam == target_prefix).all() + + # copy tokens, scores and lprobs from the first beam to all beams + tokens = self.replicate_first_beam(tokens, eos_mask_batch_dim, beam_size) + scores = self.replicate_first_beam(scores, eos_mask_batch_dim, beam_size) + lprobs = self.replicate_first_beam(lprobs, eos_mask_batch_dim, beam_size) + return lprobs, tokens, scores + + def replicate_first_beam(self, tensor, mask, beam_size: int): + tensor = tensor.view(-1, beam_size, tensor.size(-1)) + tensor[mask] = tensor[mask][:, :1, :] + return tensor.view(-1, tensor.size(-1)) + + def finalize_hypos( + self, + step: int, + bbsz_idx, + eos_scores, + tokens, + scores, + finalized: List[List[Dict[str, Tensor]]], + finished: List[bool], + beam_size: int, + attn: Optional[Tensor], + src_lengths, + max_len: int, + ): + """Finalize hypothesis, store finalized information in `finalized`, and change `finished` accordingly. + A sentence is finalized when {beam_size} finished items have been collected for it. + + Returns number of sentences (not beam items) being finalized. + These will be removed from the batch and not processed further. + Args: + bbsz_idx (Tensor): + """ + assert bbsz_idx.numel() == eos_scores.numel() + + # clone relevant token and attention tensors. + # tokens is (batch * beam, max_len). So the index_select + # gets the newly EOS rows, then selects cols 1..{step + 2} + tokens_clone = tokens.index_select(0, bbsz_idx)[ + :, 1 : step + 2 + ] # skip the first index, which is EOS + + tokens_clone[:, step] = self.eos + attn_clone = ( + attn.index_select(0, bbsz_idx)[:, :, 1 : step + 2] + if attn is not None + else None + ) + + # compute scores per token position + pos_scores = scores.index_select(0, bbsz_idx)[:, : step + 1] + pos_scores[:, step] = eos_scores + # convert from cumulative to per-position scores + pos_scores[:, 1:] = pos_scores[:, 1:] - pos_scores[:, :-1] + + # normalize sentence-level scores + if self.normalize_scores: + eos_scores /= (step + 1) ** self.len_penalty + + # cum_unfin records which sentences in the batch are finished. + # It helps match indexing between (a) the original sentences + # in the batch and (b) the current, possibly-reduced set of + # sentences. + cum_unfin: List[int] = [] + prev = 0 + for f in finished: + if f: + prev += 1 + else: + cum_unfin.append(prev) + cum_fin_tensor = torch.tensor(cum_unfin, dtype=torch.int).to(bbsz_idx) + + unfin_idx = torch.div(bbsz_idx, beam_size, rounding_mode="trunc") + sent = unfin_idx + torch.index_select(cum_fin_tensor, 0, unfin_idx) + + # Create a set of "{sent}{unfin_idx}", where + # "unfin_idx" is the index in the current (possibly reduced) + # list of sentences, and "sent" is the index in the original, + # unreduced batch + # For every finished beam item + # sentence index in the current (possibly reduced) batch + seen = (sent << 32) + unfin_idx + unique_seen: List[int] = torch.unique(seen).tolist() + + if self.match_source_len: + condition = step > torch.index_select(src_lengths, 0, unfin_idx) + eos_scores = torch.where(condition, torch.tensor(-math.inf), eos_scores) + sent_list: List[int] = sent.tolist() + for i in range(bbsz_idx.size()[0]): + # An input sentence (among those in a batch) is finished when + # beam_size hypotheses have been collected for it + if len(finalized[sent_list[i]]) < beam_size: + if attn_clone is not None: + # remove padding tokens from attn scores + hypo_attn = attn_clone[i] + else: + hypo_attn = torch.empty(0) + + finalized[sent_list[i]].append( + { + "tokens": tokens_clone[i], + "score": eos_scores[i], + "attention": hypo_attn, # src_len x tgt_len + "alignment": torch.empty(0), + "positional_scores": pos_scores[i], + } + ) + + newly_finished: List[int] = [] + for unique_s in unique_seen: + # check termination conditions for this sentence + unique_sent: int = unique_s >> 32 + unique_unfin_idx: int = unique_s - (unique_sent << 32) + + if not finished[unique_sent] and self.is_finished( + step, unique_unfin_idx, max_len, len(finalized[unique_sent]), beam_size + ): + finished[unique_sent] = True + newly_finished.append(unique_unfin_idx) + + return newly_finished + + def is_finished( + self, + step: int, + unfin_idx: int, + max_len: int, + finalized_sent_len: int, + beam_size: int, + ): + """ + Check whether decoding for a sentence is finished, which + occurs when the list of finalized sentences has reached the + beam size, or when we reach the maximum length. + """ + assert finalized_sent_len <= beam_size + if finalized_sent_len == beam_size or step == max_len: + return True + return False + + +class EnsembleModel(nn.Module): + """A wrapper around an ensemble of models.""" + + def __init__(self, models): + super().__init__() + self.models_size = len(models) + # method '__len__' is not supported in ModuleList for torch script + self.single_model = models[0] + self.models = nn.ModuleList(models) + + self.has_incremental: bool = False + if all( + hasattr(m, "decoder") and isinstance(m.decoder, FairseqIncrementalDecoder) + for m in models + ): + self.has_incremental = True + + def forward(self): + pass + + def has_encoder(self): + return hasattr(self.single_model, "encoder") + + def has_incremental_states(self): + return self.has_incremental + + def max_decoder_positions(self): + return min( + [ + m.max_decoder_positions() + for m in self.models + if hasattr(m, "max_decoder_positions") + ] + + [sys.maxsize] + ) + + def set_decoder_beam_size(self, beam_size): + """Set beam size for efficient beamable enc-dec attention.""" + if beam_size > 1: + for model in self.models: + if hasattr(model, "set_beam_size"): + model.set_beam_size(beam_size) + + @torch.jit.export + def forward_encoder(self, net_input: Dict[str, Tensor]): + if not self.has_encoder(): + return None + return [model.encoder.forward_torchscript(net_input) for model in self.models] + + @torch.jit.export + def forward_decoder( + self, + tokens, + encoder_outs: List[Dict[str, List[Tensor]]], + incremental_states: List[Dict[str, Dict[str, Optional[Tensor]]]], + temperature: float = 1.0, + ): + log_probs = [] + avg_attn: Optional[Tensor] = None + encoder_out: Optional[Dict[str, List[Tensor]]] = None + for i, model in enumerate(self.models): + if self.has_encoder(): + encoder_out = encoder_outs[i] + # decode each model + if self.has_incremental_states(): + decoder_out = model.decoder.forward( + tokens, + encoder_out=encoder_out, + incremental_state=incremental_states[i], + ) + else: + if hasattr(model, "decoder"): + decoder_out = model.decoder.forward(tokens, encoder_out=encoder_out) + else: + decoder_out = model.forward(tokens) + + attn: Optional[Tensor] = None + decoder_len = len(decoder_out) + if decoder_len > 1 and decoder_out[1] is not None: + if isinstance(decoder_out[1], Tensor): + attn = decoder_out[1] + else: + attn_holder = decoder_out[1]["attn"] + if isinstance(attn_holder, Tensor): + attn = attn_holder + elif attn_holder is not None: + attn = attn_holder[0] + if attn is not None: + attn = attn[:, -1, :] + + decoder_out_tuple = ( + decoder_out[0][:, -1:, :].div_(temperature), + None if decoder_len <= 1 else decoder_out[1], + ) + probs = model.get_normalized_probs( + decoder_out_tuple, log_probs=True, sample=None + ) + probs = probs[:, -1, :] + if self.models_size == 1: + return probs, attn + + log_probs.append(probs) + if attn is not None: + if avg_attn is None: + avg_attn = attn + else: + avg_attn.add_(attn) + + avg_probs = torch.logsumexp(torch.stack(log_probs, dim=0), dim=0) - math.log( + self.models_size + ) + + if avg_attn is not None: + avg_attn.div_(self.models_size) + return avg_probs, avg_attn + + @torch.jit.export + def reorder_encoder_out( + self, encoder_outs: Optional[List[Dict[str, List[Tensor]]]], new_order + ): + """ + Reorder encoder output according to *new_order*. + + Args: + encoder_out: output from the ``forward()`` method + new_order (LongTensor): desired order + + Returns: + *encoder_out* rearranged according to *new_order* + """ + new_outs: List[Dict[str, List[Tensor]]] = [] + if not self.has_encoder(): + return new_outs + for i, model in enumerate(self.models): + assert encoder_outs is not None + new_outs.append( + model.encoder.reorder_encoder_out(encoder_outs[i], new_order) + ) + return new_outs + + @torch.jit.export + def reorder_incremental_state( + self, + incremental_states: List[Dict[str, Dict[str, Optional[Tensor]]]], + new_order, + ): + if not self.has_incremental_states(): + return + for i, model in enumerate(self.models): + model.decoder.reorder_incremental_state_scripting( + incremental_states[i], new_order + ) + + +class SequenceGeneratorWithAlignment(SequenceGenerator): + def __init__( + self, models, tgt_dict, left_pad_target=False, print_alignment="hard", **kwargs + ): + """Generates translations of a given source sentence. + + Produces alignments following "Jointly Learning to Align and + Translate with Transformer Models" (Garg et al., EMNLP 2019). + + Args: + left_pad_target (bool, optional): Whether or not the + hypothesis should be left padded or not when they are + teacher forced for generating alignments. + """ + super().__init__(EnsembleModelWithAlignment(models), tgt_dict, **kwargs) + self.left_pad_target = left_pad_target + + if print_alignment == "hard": + self.extract_alignment = utils.extract_hard_alignment + elif print_alignment == "soft": + self.extract_alignment = utils.extract_soft_alignment + + @torch.no_grad() + def generate(self, models, sample, **kwargs): + finalized = super()._generate(sample, **kwargs) + + src_tokens = sample["net_input"]["src_tokens"] + bsz = src_tokens.shape[0] + beam_size = self.beam_size + ( + src_tokens, + src_lengths, + prev_output_tokens, + tgt_tokens, + ) = self._prepare_batch_for_alignment(sample, finalized) + if any(getattr(m, "full_context_alignment", False) for m in self.model.models): + attn = self.model.forward_align(src_tokens, src_lengths, prev_output_tokens) + else: + attn = [ + finalized[i // beam_size][i % beam_size]["attention"].transpose(1, 0) + for i in range(bsz * beam_size) + ] + + if src_tokens.device != "cpu": + src_tokens = src_tokens.to("cpu") + tgt_tokens = tgt_tokens.to("cpu") + attn = [i.to("cpu") for i in attn] + + # Process the attn matrix to extract hard alignments. + for i in range(bsz * beam_size): + alignment = self.extract_alignment( + attn[i], src_tokens[i], tgt_tokens[i], self.pad, self.eos + ) + finalized[i // beam_size][i % beam_size]["alignment"] = alignment + return finalized + + def _prepare_batch_for_alignment(self, sample, hypothesis): + src_tokens = sample["net_input"]["src_tokens"] + bsz = src_tokens.shape[0] + src_tokens = ( + src_tokens[:, None, :] + .expand(-1, self.beam_size, -1) + .contiguous() + .view(bsz * self.beam_size, -1) + ) + src_lengths = sample["net_input"]["src_lengths"] + src_lengths = ( + src_lengths[:, None] + .expand(-1, self.beam_size) + .contiguous() + .view(bsz * self.beam_size) + ) + prev_output_tokens = data_utils.collate_tokens( + [beam["tokens"] for example in hypothesis for beam in example], + self.pad, + self.eos, + self.left_pad_target, + move_eos_to_beginning=True, + ) + tgt_tokens = data_utils.collate_tokens( + [beam["tokens"] for example in hypothesis for beam in example], + self.pad, + self.eos, + self.left_pad_target, + move_eos_to_beginning=False, + ) + return src_tokens, src_lengths, prev_output_tokens, tgt_tokens + + +class EnsembleModelWithAlignment(EnsembleModel): + """A wrapper around an ensemble of models.""" + + def __init__(self, models): + super().__init__(models) + + def forward_align(self, src_tokens, src_lengths, prev_output_tokens): + avg_attn = None + for model in self.models: + decoder_out = model(src_tokens, src_lengths, prev_output_tokens) + attn = decoder_out[1]["attn"][0] + if avg_attn is None: + avg_attn = attn + else: + avg_attn.add_(attn) + if len(self.models) > 1: + avg_attn.div_(len(self.models)) + return avg_attn diff --git a/PyTorch/NLP/new-Transformer/fairseq/sequence_scorer.py b/PyTorch/NLP/new-Transformer/fairseq/sequence_scorer.py new file mode 100644 index 00000000..411d4df4 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/sequence_scorer.py @@ -0,0 +1,153 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import sys + +import torch +from fairseq import utils + + +class SequenceScorer(object): + """Scores the target for a given source sentence.""" + + def __init__( + self, + tgt_dict, + softmax_batch=None, + compute_alignment=False, + eos=None, + symbols_to_strip_from_output=None, + ): + self.pad = tgt_dict.pad() + self.eos = tgt_dict.eos() if eos is None else eos + self.softmax_batch = softmax_batch or sys.maxsize + assert self.softmax_batch > 0 + self.compute_alignment = compute_alignment + self.symbols_to_strip_from_output = ( + symbols_to_strip_from_output.union({self.eos}) + if symbols_to_strip_from_output is not None + else {self.eos} + ) + + @torch.no_grad() + def generate(self, models, sample, **kwargs): + """Score a batch of translations.""" + net_input = sample["net_input"] + + def batch_for_softmax(dec_out, target): + # assumes decoder_out[0] is the only thing needed (may not be correct for future models!) + first, rest = dec_out[0], dec_out[1:] + bsz, tsz, dim = first.shape + if bsz * tsz < self.softmax_batch: + yield dec_out, target, True + else: + flat = first.contiguous().view(1, -1, dim) + flat_tgt = target.contiguous().view(flat.shape[:-1]) + s = 0 + while s < flat.size(1): + e = s + self.softmax_batch + yield (flat[:, s:e],) + rest, flat_tgt[:, s:e], False + s = e + + def gather_target_probs(probs, target): + probs = probs.gather( + dim=2, + index=target.unsqueeze(-1), + ) + return probs + + orig_target = sample["target"] + + # compute scores for each model in the ensemble + avg_probs = None + avg_attn = None + for model in models: + model.eval() + decoder_out = model(**net_input) + attn = decoder_out[1] if len(decoder_out) > 1 else None + if type(attn) is dict: + attn = attn.get("attn", None) + + batched = batch_for_softmax(decoder_out, orig_target) + probs, idx = None, 0 + for bd, tgt, is_single in batched: + sample["target"] = tgt + curr_prob = model.get_normalized_probs( + bd, log_probs=len(models) == 1, sample=sample + ).data + if is_single: + probs = gather_target_probs(curr_prob, orig_target) + else: + if probs is None: + probs = curr_prob.new(orig_target.numel()) + step = curr_prob.size(0) * curr_prob.size(1) + end = step + idx + tgt_probs = gather_target_probs( + curr_prob.view(tgt.shape + (curr_prob.size(-1),)), tgt + ) + probs[idx:end] = tgt_probs.view(-1) + idx = end + sample["target"] = orig_target + + probs = probs.view(sample["target"].shape) + + if avg_probs is None: + avg_probs = probs + else: + avg_probs.add_(probs) + if attn is not None: + if torch.is_tensor(attn): + attn = attn.data + else: + attn = attn[0] + if avg_attn is None: + avg_attn = attn + else: + avg_attn.add_(attn) + if len(models) > 1: + avg_probs.div_(len(models)) + avg_probs.log_() + if avg_attn is not None: + avg_attn.div_(len(models)) + + bsz = avg_probs.size(0) + hypos = [] + start_idxs = sample["start_indices"] if "start_indices" in sample else [0] * bsz + for i in range(bsz): + # remove padding from ref + ref = ( + utils.strip_pad(sample["target"][i, start_idxs[i] :], self.pad) + if sample["target"] is not None + else None + ) + tgt_len = ref.numel() + avg_probs_i = avg_probs[i][start_idxs[i] : start_idxs[i] + tgt_len] + score_i = avg_probs_i.sum() / tgt_len + if avg_attn is not None: + avg_attn_i = avg_attn[i] + if self.compute_alignment: + alignment = utils.extract_hard_alignment( + avg_attn_i, + sample["net_input"]["src_tokens"][i], + sample["target"][i], + self.pad, + self.eos, + ) + else: + alignment = None + else: + avg_attn_i = alignment = None + hypos.append( + [ + { + "tokens": ref, + "score": score_i, + "attention": avg_attn_i, + "alignment": alignment, + "positional_scores": avg_probs_i, + } + ] + ) + return hypos diff --git a/PyTorch/NLP/new-Transformer/fairseq/speech_generator.py b/PyTorch/NLP/new-Transformer/fairseq/speech_generator.py new file mode 100644 index 00000000..90ec914e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/speech_generator.py @@ -0,0 +1,231 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +import numpy as np + +from fairseq.data.audio.speech_to_text_dataset import S2TDataConfig + + +class SpeechGenerator(object): + def __init__(self, model, vocoder, data_cfg: S2TDataConfig): + self.model = model + self.vocoder = vocoder + stats_npz_path = data_cfg.global_cmvn_stats_npz + self.gcmvn_stats = None + if stats_npz_path is not None: + self.gcmvn_stats = np.load(stats_npz_path) + + def gcmvn_denormalize(self, x): + # x: B x T x C + if self.gcmvn_stats is None: + return x + mean = torch.from_numpy(self.gcmvn_stats["mean"]).to(x) + std = torch.from_numpy(self.gcmvn_stats["std"]).to(x) + assert len(x.shape) == 3 and mean.shape[0] == std.shape[0] == x.shape[2] + x = x * std.view(1, 1, -1).expand_as(x) + return x + mean.view(1, 1, -1).expand_as(x) + + def get_waveform(self, feat): + # T x C -> T + return None if self.vocoder is None else self.vocoder(feat).squeeze(0) + + +class AutoRegressiveSpeechGenerator(SpeechGenerator): + def __init__( + self, + model, + vocoder, + data_cfg, + max_iter: int = 6000, + eos_prob_threshold: float = 0.5, + ): + super().__init__(model, vocoder, data_cfg) + self.max_iter = max_iter + self.eos_prob_threshold = eos_prob_threshold + + @torch.no_grad() + def generate(self, model, sample, has_targ=False, **kwargs): + model.eval() + + src_tokens = sample["net_input"]["src_tokens"] + src_lengths = sample["net_input"]["src_lengths"] + bsz, src_len = src_tokens.size()[:2] + n_frames_per_step = model.decoder.n_frames_per_step + out_dim = model.decoder.out_dim + raw_dim = out_dim // n_frames_per_step + + # initialize + encoder_out = model.forward_encoder( + src_tokens, src_lengths, speaker=sample["speaker"] + ) + incremental_state = {} + feat, attn, eos_prob = [], [], [] + finished = src_tokens.new_zeros((bsz,)).bool() + out_lens = src_lengths.new_zeros((bsz,)).long().fill_(self.max_iter) + + prev_feat_out = encoder_out["encoder_out"][0].new_zeros(bsz, 1, out_dim) + for step in range(self.max_iter): + cur_out_lens = out_lens.clone() + cur_out_lens.masked_fill_(cur_out_lens.eq(self.max_iter), step + 1) + _, cur_eos_out, cur_extra = model.forward_decoder( + prev_feat_out, + encoder_out=encoder_out, + incremental_state=incremental_state, + target_lengths=cur_out_lens, + speaker=sample["speaker"], + **kwargs + ) + cur_eos_prob = torch.sigmoid(cur_eos_out).squeeze(2) + feat.append(cur_extra["feature_out"]) + attn.append(cur_extra["attn"]) + eos_prob.append(cur_eos_prob) + + cur_finished = cur_eos_prob.squeeze(1) > self.eos_prob_threshold + out_lens.masked_fill_((~finished) & cur_finished, step + 1) + finished = finished | cur_finished + if finished.sum().item() == bsz: + break + prev_feat_out = cur_extra["feature_out"] + + feat = torch.cat(feat, dim=1) + feat = model.decoder.postnet(feat) + feat + eos_prob = torch.cat(eos_prob, dim=1) + attn = torch.cat(attn, dim=2) + alignment = attn.max(dim=1)[1] + + feat = feat.reshape(bsz, -1, raw_dim) + feat = self.gcmvn_denormalize(feat) + + eos_prob = eos_prob.repeat_interleave(n_frames_per_step, dim=1) + attn = attn.repeat_interleave(n_frames_per_step, dim=2) + alignment = alignment.repeat_interleave(n_frames_per_step, dim=1) + out_lens = out_lens * n_frames_per_step + + finalized = [ + { + "feature": feat[b, :out_len], + "eos_prob": eos_prob[b, :out_len], + "attn": attn[b, :, :out_len], + "alignment": alignment[b, :out_len], + "waveform": self.get_waveform(feat[b, :out_len]), + } + for b, out_len in zip(range(bsz), out_lens) + ] + + if has_targ: + assert sample["target"].size(-1) == out_dim + tgt_feats = sample["target"].view(bsz, -1, raw_dim) + tgt_feats = self.gcmvn_denormalize(tgt_feats) + tgt_lens = sample["target_lengths"] * n_frames_per_step + for b, (f, l) in enumerate(zip(tgt_feats, tgt_lens)): + finalized[b]["targ_feature"] = f[:l] + finalized[b]["targ_waveform"] = self.get_waveform(f[:l]) + return finalized + + +class NonAutoregressiveSpeechGenerator(SpeechGenerator): + @torch.no_grad() + def generate(self, model, sample, has_targ=False, **kwargs): + model.eval() + + bsz, max_src_len = sample["net_input"]["src_tokens"].size() + n_frames_per_step = model.encoder.n_frames_per_step + out_dim = model.encoder.out_dim + raw_dim = out_dim // n_frames_per_step + + feat, feat_post, out_lens, log_dur_out, _, _ = model( + src_tokens=sample["net_input"]["src_tokens"], + src_lengths=sample["net_input"]["src_lengths"], + prev_output_tokens=sample["net_input"]["prev_output_tokens"], + incremental_state=None, + target_lengths=sample["target_lengths"], + speaker=sample["speaker"], + ) + if feat_post is not None: + feat = feat_post + + feat = feat.view(bsz, -1, raw_dim) + feat = self.gcmvn_denormalize(feat) + + dur_out = torch.clamp(torch.round(torch.exp(log_dur_out) - 1).long(), min=0) + + def get_dur_plot_data(d): + r = [] + for i, dd in enumerate(d): + r += [i + 1] * dd.item() + return r + + out_lens = out_lens * n_frames_per_step + finalized = [ + { + "feature": feat[b, :l] if l > 0 else feat.new_zeros([1, raw_dim]), + "waveform": self.get_waveform( + feat[b, :l] if l > 0 else feat.new_zeros([1, raw_dim]) + ), + "attn": feat.new_tensor(get_dur_plot_data(dur_out[b])), + } + for b, l in zip(range(bsz), out_lens) + ] + + if has_targ: + tgt_feats = sample["target"].view(bsz, -1, raw_dim) + tgt_feats = self.gcmvn_denormalize(tgt_feats) + tgt_lens = sample["target_lengths"] * n_frames_per_step + for b, (f, l) in enumerate(zip(tgt_feats, tgt_lens)): + finalized[b]["targ_feature"] = f[:l] + finalized[b]["targ_waveform"] = self.get_waveform(f[:l]) + return finalized + + +class TeacherForcingAutoRegressiveSpeechGenerator(AutoRegressiveSpeechGenerator): + @torch.no_grad() + def generate(self, model, sample, has_targ=False, **kwargs): + model.eval() + + src_tokens = sample["net_input"]["src_tokens"] + src_lens = sample["net_input"]["src_lengths"] + prev_out_tokens = sample["net_input"]["prev_output_tokens"] + tgt_lens = sample["target_lengths"] + n_frames_per_step = model.decoder.n_frames_per_step + raw_dim = model.decoder.out_dim // n_frames_per_step + bsz = src_tokens.shape[0] + + feat, eos_prob, extra = model( + src_tokens, + src_lens, + prev_out_tokens, + incremental_state=None, + target_lengths=tgt_lens, + speaker=sample["speaker"], + ) + + attn = extra["attn"] # B x T_s x T_t + alignment = attn.max(dim=1)[1] + feat = feat.reshape(bsz, -1, raw_dim) + feat = self.gcmvn_denormalize(feat) + eos_prob = eos_prob.repeat_interleave(n_frames_per_step, dim=1) + attn = attn.repeat_interleave(n_frames_per_step, dim=2) + alignment = alignment.repeat_interleave(n_frames_per_step, dim=1) + tgt_lens = sample["target_lengths"] * n_frames_per_step + + finalized = [ + { + "feature": feat[b, :tgt_len], + "eos_prob": eos_prob[b, :tgt_len], + "attn": attn[b, :, :tgt_len], + "alignment": alignment[b, :tgt_len], + "waveform": self.get_waveform(feat[b, :tgt_len]), + } + for b, tgt_len in zip(range(bsz), tgt_lens) + ] + + if has_targ: + tgt_feats = sample["target"].view(bsz, -1, raw_dim) + tgt_feats = self.gcmvn_denormalize(tgt_feats) + for b, (f, l) in enumerate(zip(tgt_feats, tgt_lens)): + finalized[b]["targ_feature"] = f[:l] + finalized[b]["targ_waveform"] = self.get_waveform(f[:l]) + return finalized diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/__init__.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/__init__.py new file mode 100644 index 00000000..9a46b012 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/__init__.py @@ -0,0 +1,136 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +import argparse +import importlib +import os + +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.utils import merge_with_parent +from hydra.core.config_store import ConfigStore + +from .fairseq_task import FairseqTask, LegacyFairseqTask # noqa + + +# register dataclass +TASK_DATACLASS_REGISTRY = {} +TASK_REGISTRY = {} +TASK_CLASS_NAMES = set() + + +def setup_task(cfg: FairseqDataclass, **kwargs): + task = None + task_name = getattr(cfg, "task", None) + + if isinstance(task_name, str): + # legacy tasks + task = TASK_REGISTRY[task_name] + if task_name in TASK_DATACLASS_REGISTRY: + dc = TASK_DATACLASS_REGISTRY[task_name] + cfg = dc.from_namespace(cfg) + else: + task_name = getattr(cfg, "_name", None) + + if task_name and task_name in TASK_DATACLASS_REGISTRY: + dc = TASK_DATACLASS_REGISTRY[task_name] + cfg = merge_with_parent(dc(), cfg) + task = TASK_REGISTRY[task_name] + + assert ( + task is not None + ), f"Could not infer task type from {cfg}. Available argparse tasks: {TASK_REGISTRY.keys()}. Available hydra tasks: {TASK_DATACLASS_REGISTRY.keys()}" + + return task.setup_task(cfg, **kwargs) + + +def register_task(name, dataclass=None): + """ + New tasks can be added to fairseq with the + :func:`~fairseq.tasks.register_task` function decorator. + + For example:: + + @register_task('classification') + class ClassificationTask(FairseqTask): + (...) + + .. note:: + + All Tasks must implement the :class:`~fairseq.tasks.FairseqTask` + interface. + + Args: + name (str): the name of the task + """ + + def register_task_cls(cls): + if name in TASK_REGISTRY: + raise ValueError("Cannot register duplicate task ({})".format(name)) + if not issubclass(cls, FairseqTask): + raise ValueError( + "Task ({}: {}) must extend FairseqTask".format(name, cls.__name__) + ) + if cls.__name__ in TASK_CLASS_NAMES: + raise ValueError( + "Cannot register task with duplicate class name ({})".format( + cls.__name__ + ) + ) + TASK_REGISTRY[name] = cls + TASK_CLASS_NAMES.add(cls.__name__) + + if dataclass is not None and not issubclass(dataclass, FairseqDataclass): + raise ValueError( + "Dataclass {} must extend FairseqDataclass".format(dataclass) + ) + + cls.__dataclass = dataclass + if dataclass is not None: + TASK_DATACLASS_REGISTRY[name] = dataclass + + cs = ConfigStore.instance() + node = dataclass() + node._name = name + cs.store(name=name, group="task", node=node, provider="fairseq") + + return cls + + return register_task_cls + + +def get_task(name): + return TASK_REGISTRY[name] + + +def import_tasks(tasks_dir, namespace): + for file in os.listdir(tasks_dir): + path = os.path.join(tasks_dir, file) + if ( + not file.startswith("_") + and not file.startswith(".") + and (file.endswith(".py") or os.path.isdir(path)) + ): + task_name = file[: file.find(".py")] if file.endswith(".py") else file + importlib.import_module(namespace + "." + task_name) + + # expose `task_parser` for sphinx + if task_name in TASK_REGISTRY: + parser = argparse.ArgumentParser(add_help=False) + group_task = parser.add_argument_group("Task name") + # fmt: off + group_task.add_argument('--task', metavar=task_name, + help='Enable this task with: ``--task=' + task_name + '``') + # fmt: on + group_args = parser.add_argument_group( + "Additional command-line arguments" + ) + TASK_REGISTRY[task_name].add_args(group_args) + globals()[task_name + "_parser"] = parser + + +# automatically import any Python files in the tasks/ directory +tasks_dir = os.path.dirname(__file__) +import_tasks(tasks_dir, "fairseq.tasks") diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/audio_finetuning.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/audio_finetuning.py new file mode 100644 index 00000000..5e04a1b7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/audio_finetuning.py @@ -0,0 +1,343 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + +import logging +import os +import torch +import json + +from argparse import Namespace +from dataclasses import dataclass, field +from typing import Optional, Any + +from fairseq.data import AddTargetDataset, Dictionary, encoders +from fairseq.tasks.audio_pretraining import AudioPretrainingTask, AudioPretrainingConfig +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.configs import GenerationConfig +from fairseq.data.text_compressor import TextCompressor, TextCompressionLevel + +from . import register_task +from .. import utils +from ..logging import metrics + + +logger = logging.getLogger(__name__) + + +class LabelEncoder(object): + def __init__(self, dictionary): + self.dictionary = dictionary + + def __call__(self, label): + return self.dictionary.encode_line( + label, append_eos=False, add_if_not_exist=False + ) + + +def label_len_fn(label): + return len(label.split(" ")) + + +@dataclass +class AudioFinetuningConfig(AudioPretrainingConfig): + # Options for reporting WER metrics during validation. Only applicable to + # Seq2Seq models during fine-tuning + eval_wer: bool = field( + default=False, metadata={"help": "compute WER for Seq2Seq models"} + ) + eval_wer_config: GenerationConfig = field( + default_factory=lambda: GenerationConfig(), + metadata={"help": "beam search config for evaluating wer during training"}, + ) + eval_wer_tokenizer: Any = field( + default=None, + metadata={"help": "tokenizer config for evaluating wer during training"}, + ) + eval_wer_post_process: str = field( + default="letter", + metadata={ + "help": "remove BPE tokens before scoring (can be sentencepiece, letter, and more)" + }, + ) + eval_bleu: bool = field( + default=False, metadata={"help": "evaluation with BLEU scores"} + ) + eval_bleu_detok: Optional[str] = field( + default=None, + metadata={ + "help": "detokenize before computing BLEU (e.g., 'moses'); " + "required if using --eval-bleu; use 'space' to disable " + "detokenization; see fairseq.data.encoders for other options" + }, + ) + eval_bleu_detok_args: str = field( + default="{}", metadata={"help": "args for building the tokenizer, if needed"} + ) + eval_tokenized_bleu: bool = field( + default=False, metadata={"help": "compute tokenized BLEU instead of sacrebleu"} + ) + eval_bleu_remove_bpe: Optional[str] = field( + default=None, metadata={"help": "remove BPE before computing BLEU"} + ) + eval_bleu_args: str = field( + default="{}", + metadata={ + "help": "generation args for BLUE scoring, e.g., " + '\'{"beam": 4, "lenpen": 0.6}\'' + }, + ) + eval_bleu_print_samples: bool = field( + default=False, metadata={"help": "print sample generations during validation"} + ) + autoregressive: bool = field( + default=False, + metadata={ + "help": "required for autoregressive decoders (like seq2seq models); " + "adds 'prev_output_tokens' to input and appends eos to target" + }, + ) + + +@register_task("audio_finetuning", dataclass=AudioFinetuningConfig) +class AudioFinetuningTask(AudioPretrainingTask): + """ """ + + cfg: AudioFinetuningConfig + + def __init__( + self, + cfg: AudioFinetuningConfig, + ): + super().__init__(cfg) + self.blank_symbol = "" + + self.state.add_factory("target_dictionary", self.load_target_dictionary) + + def load_target_dictionary(self): + if self.cfg.labels: + dict_path = os.path.join(self.cfg.data, f"dict.{self.cfg.labels}.txt") + return Dictionary.load(dict_path) + return None + + def load_dataset( + self, split: str, task_cfg: AudioFinetuningConfig = None, **kwargs + ): + super().load_dataset(split, task_cfg, **kwargs) + + task_cfg = task_cfg or self.cfg + assert task_cfg.labels is not None + text_compression_level = getattr( + TextCompressionLevel, str(self.cfg.text_compression_level) + ) + data_path = self.cfg.data + label_path = os.path.join(data_path, f"{split}.{task_cfg.labels}") + skipped_indices = getattr(self.datasets[split], "skipped_indices", set()) + text_compressor = TextCompressor(level=text_compression_level) + with open(label_path, "r") as f: + labels = [ + text_compressor.compress(l) + for i, l in enumerate(f) + if i not in skipped_indices + ] + + assert len(labels) == len(self.datasets[split]), ( + f"labels length ({len(labels)}) and dataset length " + f"({len(self.datasets[split])}) do not match" + ) + + process_label = LabelEncoder(self.target_dictionary) + + self.datasets[split] = AddTargetDataset( + self.datasets[split], + labels, + pad=self.target_dictionary.pad(), + eos=self.target_dictionary.eos(), + batch_targets=True, + process_label=process_label, + label_len_fn=label_len_fn, + add_to_input=task_cfg.get("autoregressive", False), + text_compression_level=text_compression_level, + ) + + @property + def target_dictionary(self): + """Return the :class:`~fairseq.data.Dictionary` for the language + model.""" + return self.state.target_dictionary + + def valid_step(self, sample, model, criterion): + loss, sample_size, logging_output = super().valid_step(sample, model, criterion) + if self.cfg.eval_wer and self.cfg.autoregressive: + metrics = self._inference_with_wer(self.sequence_generator, sample, model) + logging_output["_num_char_errors"] = metrics["num_char_errors"] + logging_output["_num_chars"] = metrics["num_chars"] + logging_output["_num_word_errors"] = metrics["num_word_errors"] + logging_output["_num_words"] = metrics["num_words"] + if self.cfg.eval_bleu and self.cfg.autoregressive: + metrics = self._inference_with_bleu(self.sequence_generator, sample, model) + logging_output["_bleu_sys_len"] = metrics.sys_len + logging_output["_bleu_ref_len"] = metrics.ref_len + # we split counts into separate entries so that they can be + # summed efficiently across workers using fast-stat-sync + assert len(metrics.counts) == 4 + for i in range(4): + logging_output[f"_bleu_counts_{i}"] = metrics.counts[i] + logging_output[f"_bleu_totals_{i}"] = metrics.totals[i] + return loss, sample_size, logging_output + + def build_model(self, model_cfg: FairseqDataclass, from_checkpoint=False): + model = super().build_model(model_cfg, from_checkpoint) + + if self.cfg.eval_wer and self.cfg.autoregressive: + self.sequence_generator = self.build_generator( + [model], + self.cfg.eval_wer_config, + ) + if self.cfg.eval_wer_tokenizer: + self.tokenizer = encoders.build_tokenizer(self.cfg.eval_wer_tokenizer) + else: + self.tokenizer = None + if self.cfg.eval_bleu and self.cfg.autoregressive: + assert self.cfg.eval_bleu_detok is not None, ( + "--eval-bleu-detok is required if using --eval-bleu; " + "try --eval-bleu-detok=moses (or --eval-bleu-detok=space " + "to disable detokenization, e.g., when using sentencepiece)" + ) + detok_args = json.loads(self.cfg.eval_bleu_detok_args) + self.tokenizer = encoders.build_tokenizer( + Namespace(tokenizer=self.cfg.eval_bleu_detok, **detok_args) + ) + gen_args = json.loads(self.cfg.eval_bleu_args) + gen_args = Namespace(**gen_args) + self.sequence_generator = self.build_generator([model], gen_args) + + return model + + def _inference_with_wer(self, generator, sample, model): + import editdistance + + def decode(toks): + s = self.target_dictionary.string( + toks.int().cpu(), + self.cfg.eval_wer_post_process, + escape_unk=True, + ) + if self.tokenizer: + s = self.tokenizer.decode(s) + return s + + num_word_errors, num_char_errors = 0, 0 + num_chars, num_words = 0, 0 + gen_out = self.inference_step(generator, [model], sample, None) + for i in range(len(gen_out)): + hyp = decode(gen_out[i][0]["tokens"]) + ref = decode( + utils.strip_pad(sample["target"][i], self.target_dictionary.pad()), + ) + num_char_errors += editdistance.eval(hyp, ref) + num_chars += len(ref) + hyp_words = hyp.split() + ref_words = ref.split() + num_word_errors += editdistance.eval(hyp_words, ref_words) + num_words += len(ref_words) + + return { + "num_char_errors": num_char_errors, + "num_chars": num_chars, + "num_word_errors": num_word_errors, + "num_words": num_words, + } + + def _inference_with_bleu(self, generator, sample, model): + import sacrebleu + + def decode(toks, is_ref): + s = self.target_dictionary.string( + toks.int().cpu(), + self.cfg.eval_bleu_remove_bpe, + # The default unknown string in fairseq is ``, but + # this is tokenized by sacrebleu as `< unk >`, inflating + # BLEU scores. Instead, we use a somewhat more verbose + # alternative that is unlikely to appear in the real + # reference, but doesn't get split into multiple tokens. + unk_string=("UNKNOWNTOKENINREF" if is_ref else "UNKNOWNTOKENINHYP"), + ) + if self.tokenizer: + s = self.tokenizer.decode(s) + return s + + gen_out = self.inference_step(generator, [model], sample) + hyps, refs = [], [] + for i in range(len(gen_out)): + hyps.append(decode(gen_out[i][0]["tokens"], is_ref=False)) + refs.append( + decode( + utils.strip_pad(sample["target"][i], self.target_dictionary.pad()), + is_ref=True, # don't count as matches to the hypo + ) + ) + if self.cfg.eval_bleu_print_samples: + logger.info("H-{} {}".format(sample["id"][0], hyps[0])) + logger.info("T-{} {}".format(sample["id"][0], refs[0])) + + eval_tokenization = "none" if self.cfg.eval_tokenized_bleu else "13a" + return sacrebleu.corpus_bleu(hyps, [refs], tokenize=eval_tokenization) + + def reduce_metrics(self, logging_outputs, criterion): + super().reduce_metrics(logging_outputs, criterion) + + if self.cfg.eval_wer: + zero = torch.scalar_tensor(0.0) + num_char_errors = sum( + log.get("_num_char_errors", zero) for log in logging_outputs + ) + num_chars = sum(log.get("_num_chars", zero) for log in logging_outputs) + num_word_errors = sum( + log.get("_num_word_errors", zero) for log in logging_outputs + ) + num_words = sum(log.get("_num_words", zero) for log in logging_outputs) + metrics.log_scalar("_num_char_errors", num_char_errors) + metrics.log_scalar("_num_chars", num_chars) + metrics.log_scalar("_num_word_errors", num_word_errors) + metrics.log_scalar("_num_words", num_words) + if num_chars > 0: + metrics.log_derived( + "uer", + lambda meters: meters["_num_char_errors"].sum + * 100.0 + / meters["_num_chars"].sum + if meters["_num_chars"].sum > 0 + else float("nan"), + ) + if num_words > 0: + metrics.log_derived( + "wer", + lambda meters: meters["_num_word_errors"].sum + * 100.0 + / meters["_num_words"].sum + if meters["_num_words"].sum > 0 + else float("nan"), + ) + if self.cfg.eval_bleu: + len_keys = ["_bleu_sys_len", "_bleu_ref_len"] + count_keys = [f"_bleu_counts_{i}" for i in range(4)] + total_keys = [f"_bleu_totals_{i}" for i in range(4)] + for k in len_keys + count_keys + total_keys: + metrics.log_scalar(k, sum(log.get(k, 0) for log in logging_outputs)) + + import sacrebleu + + metrics.log_derived( + "bleu", + lambda meters: sacrebleu.compute_bleu( + correct=[meters[k].sum for k in count_keys], + total=[meters[k].sum for k in total_keys], + sys_len=meters["_bleu_sys_len"].sum, + ref_len=meters["_bleu_ref_len"].sum, + smooth_method="exp", + ).score, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/audio_pretraining.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/audio_pretraining.py new file mode 100644 index 00000000..a55c7040 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/audio_pretraining.py @@ -0,0 +1,205 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + +import logging +import os +import sys + +from argparse import Namespace +from dataclasses import dataclass, field +from typing import Optional +from omegaconf import MISSING, II, OmegaConf + +from fairseq.data import BinarizedAudioDataset, FileAudioDataset +from fairseq.dataclass import FairseqDataclass, ChoiceEnum +from fairseq.data.text_compressor import TextCompressionLevel + +from . import FairseqTask, register_task + + +logger = logging.getLogger(__name__) + + +@dataclass +class InferredW2vConfig: + # The following are needed to precompute mask and mask channel indices + # before model's forward. + mask_length: Optional[int] = II("model.mask_length") + mask_prob: Optional[float] = II("model.mask_prob") + mask_selection: Optional[str] = II("model.mask_selection") + mask_other: Optional[float] = II("model.mask_other") + no_mask_overlap: Optional[bool] = II("model.no_mask_overlap") + mask_min_space: Optional[int] = II("model.mask_min_space") + mask_channel_length: Optional[int] = II("model.mask_channel_length") + mask_channel_prob: Optional[float] = II("model.mask_channel_prob") + mask_channel_selection: Optional[str] = II("model.mask_channel_selection") + mask_channel_other: Optional[float] = II("model.mask_channel_other") + no_mask_channel_overlap: Optional[bool] = II("model.no_mask_channel_overlap") + mask_channel_min_space: Optional[int] = II("model.mask_channel_min_space") + + conv_feature_layers: Optional[str] = II("model.conv_feature_layers") + encoder_embed_dim: Optional[int] = II("model.encoder_embed_dim") + + +@dataclass +class AudioPretrainingConfig(FairseqDataclass): + data: str = field(default=MISSING, metadata={"help": "path to data directory"}) + labels: Optional[str] = field( + default=None, + metadata={"help": "extension of the label file to load, used for fine-tuning"}, + ) + binarized_dataset: bool = field( + default=False, + metadata={ + "help": "if true, loads binarized dataset (useful for very large datasets). " + "See examples/wav2vec/scripts/binarize_manifest.sh" + }, + ) + sample_rate: int = field( + default=16_000, + metadata={ + "help": "target sample rate. audio files will be up/down sampled to this rate" + }, + ) + normalize: bool = field( + default=False, + metadata={"help": "if set, normalizes input to have 0 mean and unit variance"}, + ) + enable_padding: bool = field( + default=False, metadata={"help": "pad shorter samples instead of cropping"} + ) + max_sample_size: Optional[int] = field( + default=None, metadata={"help": "max sample size to crop to for batching"} + ) + min_sample_size: Optional[int] = field( + default=None, metadata={"help": "min sample size to skip small examples"} + ) + num_batch_buckets: int = field( + default=0, + metadata={"help": "number of buckets"}, + ) + precompute_mask_indices: bool = field( + default=False, + metadata={ + "help": "flag to compute mask indices in data preparation.", + }, + ) + + inferred_w2v_config: Optional[InferredW2vConfig] = field( + default=None, + metadata={ + "help": "wav2vec 2.0 masking arguments used to pre-compute masks (required for TPU)", + }, + ) + + tpu: bool = II("common.tpu") + text_compression_level: ChoiceEnum([x.name for x in TextCompressionLevel]) = field( + default="none", + metadata={ + "help": "compression level for texts (e.g. audio filenames, " + "target texts): none/low/high (default: none). " + }, + ) + + +@register_task("audio_pretraining", dataclass=AudioPretrainingConfig) +class AudioPretrainingTask(FairseqTask): + """ """ + + cfg: AudioPretrainingConfig + + @classmethod + def setup_task(cls, cfg: AudioPretrainingConfig, **kwargs): + """Setup the task (e.g., load dictionaries). + + Args: + cfg (AudioPretrainingConfig): configuration of this task + """ + + return cls(cfg) + + def _get_mask_precompute_kwargs(self, cfg): + if self.cfg.precompute_mask_indices or self.cfg.tpu: + assert ( + cfg.inferred_w2v_config is not None + ), "inferred_w2v_config must be set" + return OmegaConf.to_container( + cfg.inferred_w2v_config, resolve=True, enum_to_str=True + ) + else: + return {} + + def load_dataset(self, split: str, task_cfg: FairseqDataclass = None, **kwargs): + data_path = self.cfg.data + task_cfg = task_cfg or self.cfg + + # upgrade old task + if isinstance(task_cfg, Namespace): + if not hasattr(task_cfg, "autoregressive"): + task_cfg.autoregressive = not task_cfg.criterion == "ctc" + + text_compression_level = getattr( + TextCompressionLevel, str(self.cfg.text_compression_level) + ) + if getattr(task_cfg, "binarized_dataset", False): + self.datasets[split] = BinarizedAudioDataset( + data_path, + split=split, + sample_rate=task_cfg.get("sample_rate", self.cfg.sample_rate), + max_sample_size=self.cfg.max_sample_size, + min_sample_size=self.cfg.min_sample_size, + pad=task_cfg.labels is not None or task_cfg.enable_padding, + normalize=task_cfg.normalize, + num_buckets=self.cfg.num_batch_buckets or int(self.cfg.tpu), + compute_mask_indices=(self.cfg.precompute_mask_indices or self.cfg.tpu), + **self._get_mask_precompute_kwargs(task_cfg), + ) + else: + manifest_path = os.path.join(data_path, "{}.tsv".format(split)) + + self.datasets[split] = FileAudioDataset( + manifest_path=manifest_path, + sample_rate=task_cfg.get("sample_rate", self.cfg.sample_rate), + max_sample_size=self.cfg.max_sample_size, + min_sample_size=self.cfg.min_sample_size, + pad=task_cfg.labels is not None or task_cfg.enable_padding, + normalize=task_cfg.normalize, + num_buckets=self.cfg.num_batch_buckets or int(self.cfg.tpu), + compute_mask_indices=(self.cfg.precompute_mask_indices or self.cfg.tpu), + text_compression_level=text_compression_level, + **self._get_mask_precompute_kwargs(task_cfg), + ) + + if self.cfg.tpu and task_cfg.inferred_w2v_config.mask_channel_prob == 0.0: + logger.info( + "Pretraining on TPUs may suffer convergence " + "issues when training with `mask_channel_prob` value of " + "0. You may want to set this to a low value close to 0." + ) + + @property + def source_dictionary(self): + return None + + @property + def target_dictionary(self): + return None + + def max_positions(self): + """Maximum input length supported by the encoder.""" + return sys.maxsize, sys.maxsize + + def build_model(self, model_cfg: FairseqDataclass, from_checkpoint=False): + model = super().build_model(model_cfg, from_checkpoint) + + actualized_cfg = getattr(model, "cfg", None) + if actualized_cfg is not None: + # if "w2v_args" in actualized_cfg: + if hasattr(actualized_cfg, "w2v_args"): + model_cfg.w2v_args = actualized_cfg.w2v_args + + return model diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/cross_lingual_lm.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/cross_lingual_lm.py new file mode 100644 index 00000000..8f8fe7e2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/cross_lingual_lm.py @@ -0,0 +1,191 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import itertools +import logging +import os +from collections import OrderedDict + +import numpy as np +from fairseq import tokenizer, utils +from fairseq.data import ConcatDataset, Dictionary, TokenBlockDataset, data_utils +from fairseq.data.legacy.masked_lm_dataset import MaskedLMDataset +from fairseq.data.legacy.masked_lm_dictionary import MaskedLMDictionary +from fairseq.data.multi_corpus_sampled_dataset import MultiCorpusSampledDataset +from fairseq.tasks import LegacyFairseqTask, register_task + + +logger = logging.getLogger(__name__) + + +@register_task("cross_lingual_lm") +class CrossLingualLMTask(LegacyFairseqTask): + """ + Task for training cross-lingual language models. + + For more details look at: https://arxiv.org/pdf/1901.07291.pdf + + Args: + dictionary (Dictionary): the dictionary for the input of the task + """ + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + parser.add_argument( + "data", + help="colon separated path to data directories list, \ + will be iterated upon during epochs in round-robin manner", + ) + parser.add_argument( + "--tokens-per-sample", + default=512, + type=int, + help="max number of total tokens over all segments" " per sample", + ) + parser.add_argument( + "--monolingual-langs", + default="en", + type=str, + help="comma separated list of languages for which we" + " want to train XLM on", + ) + parser.add_argument( + "--shuffle", + action="store_true", + help="shuffle each monolingual dataset while" " training", + ) + + def __init__(self, args, dictionary): + super().__init__(args) + self.dictionary = dictionary + self.seed = args.seed + self.distributed_world_size = args.distributed_world_size + self.langs2id = self._lang_to_id(args.monolingual_langs) + + def _lang_to_id(self, languages: str): + """ + Build a map from languages to ids. These ids are used as segment labels + for cross-lingual LM training. + """ + lang2id = {} + langs = [l.strip() for l in languages.split(",")] + for id, lang in enumerate(langs): + lang2id[lang] = id + return lang2id + + @classmethod + def load_dictionary(cls, filename): + return MaskedLMDictionary.load(filename) + + @classmethod + def build_dictionary( + cls, filenames, workers=1, threshold=-1, nwords=-1, padding_factor=8 + ): + d = MaskedLMDictionary() + for filename in filenames: + Dictionary.add_file_to_dictionary( + filename, d, tokenizer.tokenize_line, workers + ) + d.finalize(threshold=threshold, nwords=nwords, padding_factor=padding_factor) + return d + + @property + def target_dictionary(self): + return self.dictionary + + @classmethod + def setup_task(cls, args, **kwargs): + """Setup the task.""" + dictionary = MaskedLMDictionary.load(os.path.join(args.data, "dict.txt")) + logger.info("dictionary: {} types".format(len(dictionary))) + return cls(args, dictionary) + + def _load_single_lang_dataset(self, split, epoch): + loaded_datasets = [] + + paths = utils.split_paths(self.args.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + + for k in itertools.count(): + split_k = split + (str(k) if k > 0 else "") + path = os.path.join(data_path, split_k) + + ds = data_utils.load_indexed_dataset( + path, self.dictionary, self.args.dataset_impl + ) + if ds is None: + if k > 0: + break + else: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, data_path) + ) + + # Since we append each block with the classification_token, + # we need to effectively create blocks of length + # tokens_per_sample-1 + loaded_datasets.append( + TokenBlockDataset( + ds, + ds.sizes, + self.args.tokens_per_sample - 1, + pad=self.dictionary.pad(), + eos=self.dictionary.eos(), + ) + ) + + logger.info( + "{} {} {} examples".format(data_path, split_k, len(loaded_datasets[-1])) + ) + + if len(loaded_datasets) == 1: + dataset = loaded_datasets[0] + sizes = dataset.sizes + else: + dataset = ConcatDataset(loaded_datasets) + sizes = np.concatenate([ds.sizes for ds in loaded_datasets]) + + return dataset, sizes + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + dataset_map = OrderedDict() + + for lang in self.langs2id.keys(): + # Datasets are expected to be in "split.lang" format (Eg: train.en) + language_split = "{}.{}".format(split, lang) + + block_dataset, sizes = self._load_single_lang_dataset( + split=language_split, epoch=epoch + ) + + dataset_map[lang] = MaskedLMDataset( + dataset=block_dataset, + sizes=sizes, + vocab=self.dictionary, + pad_idx=self.dictionary.pad(), + mask_idx=self.dictionary.mask(), + classif_token_idx=self.dictionary.eos(), + sep_token_idx=self.dictionary.eos(), + shuffle=getattr(self.args, "shuffle", False), + has_pairs=False, + segment_id=self.langs2id[lang], + seed=self.seed, + ) + + self.datasets[split] = MultiCorpusSampledDataset(dataset_map) + logger.info( + "{} {} {} examples".format( + utils.split_paths(self.args.data)[epoch - 1], + split, + len(self.datasets[split]), + ) + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/denoising.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/denoising.py new file mode 100644 index 00000000..1d4f84c0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/denoising.py @@ -0,0 +1,276 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os + +from fairseq import utils +from fairseq.data import ( + AppendTokenDataset, + DenoisingDataset, + Dictionary, + IdDataset, + NestedDictionaryDataset, + NumelDataset, + PadDataset, + PrependTokenDataset, + StripTokenDataset, + TokenBlockDataset, + data_utils, +) +from fairseq.data.encoders.utils import get_whole_word_mask +from fairseq.data.shorten_dataset import maybe_shorten_dataset +from fairseq.tasks import LegacyFairseqTask, register_task +import numpy as np + + +logger = logging.getLogger(__name__) + + +@register_task("denoising") +class DenoisingTask(LegacyFairseqTask): + """ + Denoising task for applying sequence to sequence denoising. (ie. BART) + """ + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + parser.add_argument("data", help="path to data directory") + parser.add_argument( + "--tokens-per-sample", + default=512, + type=int, + help="max number of total tokens over all segments" + " per sample for dataset", + ) + parser.add_argument( + "--sample-break-mode", + default="complete_doc", + type=str, + help="mode for breaking sentence", + ) + parser.add_argument( + "--mask", + default=0.0, + type=float, + help="fraction of words/subwords that will be masked", + ) + parser.add_argument( + "--mask-random", + default=0.0, + type=float, + help="instead of using [MASK], use random token this often", + ) + parser.add_argument( + "--insert", + default=0.0, + type=float, + help="insert this percentage of additional random tokens", + ) + parser.add_argument( + "--permute", + default=0.0, + type=float, + help="take this proportion of subwords and permute them", + ) + parser.add_argument( + "--rotate", + default=0.5, + type=float, + help="rotate this proportion of inputs", + ) + parser.add_argument( + "--poisson-lambda", + default=3.0, + type=float, + help="randomly shuffle sentences for this proportion of inputs", + ) + parser.add_argument( + "--permute-sentences", + default=0.0, + type=float, + help="shuffle this proportion of sentences in all inputs", + ) + parser.add_argument( + "--mask-length", + default="subword", + type=str, + choices=["subword", "word", "span-poisson"], + help="mask length to choose", + ) + parser.add_argument( + "--replace-length", + default=-1, + type=int, + help="when masking N tokens, replace with 0, 1, or N tokens (use -1 for N)", + ) + parser.add_argument( + "--max-source-positions", + default=1024, + type=int, + metavar="N", + help="max number of tokens in the source sequence", + ) + parser.add_argument( + "--max-target-positions", + default=1024, + type=int, + metavar="N", + help="max number of tokens in the target sequence", + ) + + parser.add_argument( + "--shorten-method", + default="none", + choices=["none", "truncate", "random_crop"], + help="if not none, shorten sequences that exceed --tokens-per-sample", + ) + parser.add_argument( + "--shorten-data-split-list", + default="", + help="comma-separated list of dataset splits to apply shortening to, " + 'e.g., "train,valid" (default: all dataset splits)', + ) + + def __init__(self, args, dictionary): + super().__init__(args) + self.dictionary = dictionary + self.seed = args.seed + + # add mask token + self.mask_idx = self.dictionary.add_symbol("") + + @classmethod + def setup_task(cls, args, **kwargs): + """Setup the task.""" + paths = utils.split_paths(args.data) + assert len(paths) > 0 + dictionary = Dictionary.load(os.path.join(paths[0], "dict.txt")) + logger.info("dictionary: {} types".format(len(dictionary))) + if not hasattr(args, "shuffle_instance"): + args.shuffle_instance = False + return cls(args, dictionary) + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + paths = utils.split_paths(self.args.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + split_path = os.path.join(data_path, split) + + dataset = data_utils.load_indexed_dataset( + split_path, + self.dictionary, + self.args.dataset_impl, + combine=combine, + ) + if dataset is None: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, split_path) + ) + + dataset = StripTokenDataset(dataset, self.dictionary.eos()) + + dataset = maybe_shorten_dataset( + dataset, + split, + self.args.shorten_data_split_list, + self.args.shorten_method, + self.args.tokens_per_sample, + self.args.seed, + ) + + # create continuous blocks of tokens + dataset = TokenBlockDataset( + dataset, + dataset.sizes, + self.args.tokens_per_sample - 2, # one less for and one for + pad=self.dictionary.pad(), + eos=self.dictionary.eos(), + break_mode=self.args.sample_break_mode, + document_sep_len=0, + ) + logger.info("loaded {} blocks from: {}".format(len(dataset), split_path)) + + # prepend beginning-of-sentence token (, equiv. to [CLS] in BERT) + dataset = PrependTokenDataset(dataset, self.source_dictionary.bos()) + dataset = AppendTokenDataset(dataset, self.source_dictionary.eos()) + + mask_whole_words = ( + get_whole_word_mask(self.args, self.source_dictionary) + if self.args.mask_length != "subword" + else None + ) + + self.datasets[split] = DenoisingDataset( + dataset, + dataset.sizes, + self.dictionary, + self.mask_idx, + mask_whole_words, + shuffle=self.args.shuffle_instance, + seed=self.seed, + args=self.args, + ) + logger.info( + "Split: {0}, Loaded {1} samples of denoising_dataset".format( + split, + len(self.datasets[split]), + ) + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, **kwargs): + """ + Generate batches for inference. We assume that the input begins with a + bos symbol (``) and ends with an eos symbol (``). + """ + pad = self.source_dictionary.pad() + eos = self.source_dictionary.eos() + src_dataset = TokenBlockDataset( + src_tokens, + src_lengths, + block_size=self.args.tokens_per_sample - 2, # for and + pad=pad, + eos=eos, + break_mode=self.args.sample_break_mode, + document_sep_len=0, + ) + prev_output_tokens = PrependTokenDataset( + StripTokenDataset(src_dataset, eos), eos + ) + src_dataset = PadDataset(src_dataset, pad_idx=pad, left_pad=False) + return NestedDictionaryDataset( + { + "id": IdDataset(), + "net_input": { + "src_tokens": src_dataset, + "src_lengths": NumelDataset(src_dataset, reduce=False), + "prev_output_tokens": PadDataset( + prev_output_tokens, pad_idx=pad, left_pad=False + ), + }, + "target": src_dataset, + }, + sizes=[np.array(src_lengths)], + ) + + def max_positions(self): + """Return the max sentence length allowed by the task.""" + return (self.args.max_source_positions, self.args.max_target_positions) + + @property + def source_dictionary(self): + """Return the source :class:`~fairseq.data.Dictionary`.""" + return self.dictionary + + @property + def target_dictionary(self): + """Return the target :class:`~fairseq.data.Dictionary`.""" + return self.dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/fairseq_task.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/fairseq_task.py new file mode 100644 index 00000000..273dbdda --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/fairseq_task.py @@ -0,0 +1,688 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +import warnings +from argparse import Namespace +from typing import Any, Callable, Dict, List + +import torch +from fairseq import metrics, search, tokenizer, utils +from fairseq.data import Dictionary, FairseqDataset, data_utils, encoders, iterators +from fairseq.dataclass import FairseqDataclass +from fairseq.dataclass.utils import gen_parser_from_dataclass +from fairseq.optim.amp_optimizer import AMPOptimizer +from omegaconf import DictConfig + + +logger = logging.getLogger(__name__) + + +class StatefulContainer(object): + def __init__(self): + self._state = dict() + self._factories = dict() + + def add_factory(self, name, factory: Callable[[], Any]): + self._factories[name] = factory + + def merge_state_dict(self, state_dict: Dict[str, Any]): + self._state.update(state_dict) + + @property + def state_dict(self) -> Dict[str, Any]: + return self._state + + def __getattr__(self, name): + if name not in self._state and name in self._factories: + self._state[name] = self._factories[name]() + + if name in self._state: + return self._state[name] + + raise AttributeError(f"Task state has no factory for attribute {name}") + + +class FairseqTask(object): + """ + Tasks store dictionaries and provide helpers for loading/iterating over + Datasets, initializing the Model/Criterion and calculating the loss. + + Tasks have limited statefulness. In particular, state that needs to be + saved to/loaded from checkpoints needs to be stored in the `self.state` + :class:`StatefulContainer` object. For example:: + + self.state.add_factory("dictionary", self.load_dictionary) + print(self.state.dictionary) # calls self.load_dictionary() + + This is necessary so that when loading checkpoints, we can properly + recreate the task state after initializing the task instance. + """ + + @classmethod + def add_args(cls, parser): + """Add task-specific arguments to the parser.""" + dc = getattr(cls, "__dataclass", None) + if dc is not None: + gen_parser_from_dataclass(parser, dc()) + + @staticmethod + def logging_outputs_can_be_summed(criterion) -> bool: + """ + Whether the logging outputs returned by `train_step` and `valid_step` can + be summed across workers prior to calling `aggregate_logging_outputs`. + Setting this to True will improves distributed training speed. + """ + return criterion.logging_outputs_can_be_summed() + + def __init__(self, cfg: FairseqDataclass, **kwargs): + self.cfg = cfg + self.datasets = dict() + self.dataset_to_epoch_iter = dict() + self.state = StatefulContainer() + + @classmethod + def load_dictionary(cls, filename): + """Load the dictionary from the filename + + Args: + filename (str): the filename + """ + return Dictionary.load(filename) + + @classmethod + def build_dictionary( + cls, filenames, workers=1, threshold=-1, nwords=-1, padding_factor=8 + ): + """Build the dictionary + + Args: + filenames (list): list of filenames + workers (int): number of concurrent workers + threshold (int): defines the minimum word count + nwords (int): defines the total number of words in the final dictionary, + including special symbols + padding_factor (int): can be used to pad the dictionary size to be a + multiple of 8, which is important on some hardware (e.g., Nvidia + Tensor Cores). + """ + d = Dictionary() + for filename in filenames: + Dictionary.add_file_to_dictionary( + filename, d, tokenizer.tokenize_line, workers + ) + d.finalize(threshold=threshold, nwords=nwords, padding_factor=padding_factor) + return d + + @classmethod + def setup_task(cls, cfg: DictConfig, **kwargs): + """Setup the task (e.g., load dictionaries). + + Args: + cfg (omegaconf.DictConfig): parsed command-line arguments + """ + return cls(cfg, **kwargs) + + def has_sharded_data(self, split): + return os.pathsep in getattr(self.cfg, "data", "") + + def load_dataset( + self, + split: str, + combine: bool = False, + task_cfg: FairseqDataclass = None, + **kwargs, + ): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + combine (bool): combines a split segmented into pieces into one dataset + task_cfg (FairseqDataclass): optional task configuration stored in the checkpoint that can be used + to load datasets + """ + raise NotImplementedError + + def dataset(self, split): + """ + Return a loaded dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + + Returns: + a :class:`~fairseq.data.FairseqDataset` corresponding to *split* + """ + from fairseq.data import FairseqDataset + + if split not in self.datasets: + raise KeyError("Dataset not loaded: " + split) + if not isinstance(self.datasets[split], FairseqDataset): + raise TypeError("Datasets are expected to be of type FairseqDataset") + return self.datasets[split] + + def filter_indices_by_size( + self, indices, dataset, max_positions=None, ignore_invalid_inputs=False + ): + """ + Filter examples that are too large + + Args: + indices (np.array): original array of sample indices + dataset (~fairseq.data.FairseqDataset): dataset to batch + max_positions (optional): max sentence length supported by the + model (default: None). + ignore_invalid_inputs (bool, optional): don't raise Exception for + sentences that are too long (default: False). + Returns: + np.array: array of filtered sample indices + """ + indices, ignored = dataset.filter_indices_by_size(indices, max_positions) + if len(ignored) > 0: + if not ignore_invalid_inputs: + raise Exception( + ( + "Size of sample #{} is invalid (={}) since max_positions={}, " + "skip this example with --skip-invalid-size-inputs-valid-test" + ).format(ignored[0], dataset.size(ignored[0]), max_positions) + ) + logger.warning( + ( + "{:,} samples have invalid sizes and will be skipped, " + "max_positions={}, first few sample ids={}" + ).format(len(ignored), max_positions, ignored[:10]) + ) + return indices + + def can_reuse_epoch_itr(self, dataset): + # We can reuse the epoch iterator across epochs as long as the dataset + # hasn't disabled it. We default to ``False`` here, although in practice + # this will be ``True`` for most datasets that inherit from + # ``FairseqDataset`` due to the base implementation there. + return getattr(dataset, "can_reuse_epoch_itr_across_epochs", False) + + def get_batch_iterator( + self, + dataset, + max_tokens=None, + max_sentences=None, + max_positions=None, + ignore_invalid_inputs=False, + required_batch_size_multiple=1, + seed=1, + num_shards=1, + shard_id=0, + num_workers=0, + epoch=1, + data_buffer_size=0, + disable_iterator_cache=False, + skip_remainder_batch=False, + grouped_shuffling=False, + update_epoch_batch_itr=False, + ): + """ + Get an iterator that yields batches of data from the given dataset. + + Args: + dataset (~fairseq.data.FairseqDataset): dataset to batch + max_tokens (int, optional): max number of tokens in each batch + (default: None). + max_sentences (int, optional): max number of sentences in each + batch (default: None). + max_positions (optional): max sentence length supported by the + model (default: None). + ignore_invalid_inputs (bool, optional): don't raise Exception for + sentences that are too long (default: False). + required_batch_size_multiple (int, optional): require batch size to + be a multiple of N (default: 1). + seed (int, optional): seed for random number generator for + reproducibility (default: 1). + num_shards (int, optional): shard the data iterator into N + shards (default: 1). + shard_id (int, optional): which shard of the data iterator to + return (default: 0). + num_workers (int, optional): how many subprocesses to use for data + loading. 0 means the data will be loaded in the main process + (default: 0). + epoch (int, optional): the epoch to start the iterator from + (default: 1). + data_buffer_size (int, optional): number of batches to + preload (default: 0). + disable_iterator_cache (bool, optional): don't cache the + EpochBatchIterator (ignores `FairseqTask::can_reuse_epoch_itr`) + (default: False). + skip_remainder_batch (bool, optional): if set, discard the last + batch in each training epoch, as the last batch is often smaller than + local_batch_size * distributed_word_size (default: ``True``). + grouped_shuffling (bool, optional): group batches with each groups + containing num_shards batches and shuffle groups. Reduces difference + between sequence lengths among workers for batches sorted by length. + update_epoch_batch_itr (bool optional): if true then donot use the cached + batch iterator for the epoch + + Returns: + ~fairseq.iterators.EpochBatchIterator: a batched iterator over the + given dataset split + """ + can_reuse_epoch_itr = ( + not disable_iterator_cache + and not update_epoch_batch_itr + and self.can_reuse_epoch_itr(dataset) + ) + if can_reuse_epoch_itr and dataset in self.dataset_to_epoch_iter: + logger.debug("reusing EpochBatchIterator for epoch {}".format(epoch)) + return self.dataset_to_epoch_iter[dataset] + + assert isinstance(dataset, FairseqDataset) + + # initialize the dataset with the correct starting epoch + dataset.set_epoch(epoch) + + # get indices ordered by example size + with data_utils.numpy_seed(seed): + indices = dataset.ordered_indices() + + # filter examples that are too large + if max_positions is not None: + indices = self.filter_indices_by_size( + indices, dataset, max_positions, ignore_invalid_inputs + ) + + # create mini-batches with given size constraints + batch_sampler = dataset.batch_by_size( + indices, + max_tokens=max_tokens, + max_sentences=max_sentences, + required_batch_size_multiple=required_batch_size_multiple, + ) + + # return a reusable, sharded iterator + epoch_iter = iterators.EpochBatchIterator( + dataset=dataset, + collate_fn=dataset.collater, + batch_sampler=batch_sampler, + seed=seed, + num_shards=num_shards, + shard_id=shard_id, + num_workers=num_workers, + epoch=epoch, + buffer_size=data_buffer_size, + skip_remainder_batch=skip_remainder_batch, + grouped_shuffling=grouped_shuffling, + ) + + if can_reuse_epoch_itr: + self.dataset_to_epoch_iter[dataset] = epoch_iter + + return epoch_iter + + def build_model(self, cfg: FairseqDataclass, from_checkpoint=False): + """ + Build the :class:`~fairseq.models.BaseFairseqModel` instance for this + task. + + Args: + cfg (FairseqDataclass): configuration object + + Returns: + a :class:`~fairseq.models.BaseFairseqModel` instance + """ + from fairseq import models, quantization_utils + + model = models.build_model(cfg, self, from_checkpoint) + model = quantization_utils.quantize_model_scalar(model, cfg) + return model + + def build_criterion(self, cfg: DictConfig): + """ + Build the :class:`~fairseq.criterions.FairseqCriterion` instance for + this task. + + Args: + cfg (omegaconf.DictConfig): configration object + + Returns: + a :class:`~fairseq.criterions.FairseqCriterion` instance + """ + from fairseq import criterions + + return criterions.build_criterion(cfg, self) + + def build_generator( + self, + models, + args, + seq_gen_cls=None, + extra_gen_cls_kwargs=None, + prefix_allowed_tokens_fn=None, + ): + """ + Build a :class:`~fairseq.SequenceGenerator` instance for this + task. + + Args: + models (List[~fairseq.models.FairseqModel]): ensemble of models + args (fairseq.dataclass.configs.GenerationConfig): + configuration object (dataclass) for generation + extra_gen_cls_kwargs (Dict[str, Any]): extra options to pass + through to SequenceGenerator + prefix_allowed_tokens_fn (Callable[[int, torch.Tensor], List[int]]): + If provided, this function constrains the beam search to + allowed tokens only at each step. The provided function + should take 2 arguments: the batch ID (`batch_id: int`) + and a unidimensional tensor of token ids (`inputs_ids: + torch.Tensor`). It has to return a `List[int]` with the + allowed tokens for the next generation step conditioned + on the previously generated tokens (`inputs_ids`) and + the batch ID (`batch_id`). This argument is useful for + constrained generation conditioned on the prefix, as + described in "Autoregressive Entity Retrieval" + (https://arxiv.org/abs/2010.00904) and + https://github.com/facebookresearch/GENRE. + """ + if getattr(args, "score_reference", False): + from fairseq.sequence_scorer import SequenceScorer + + return SequenceScorer( + self.target_dictionary, + compute_alignment=getattr(args, "print_alignment", False), + ) + + from fairseq.sequence_generator import ( + SequenceGenerator, + SequenceGeneratorWithAlignment, + ) + + # Choose search strategy. Defaults to Beam Search. + sampling = getattr(args, "sampling", False) + sampling_topk = getattr(args, "sampling_topk", -1) + sampling_topp = getattr(args, "sampling_topp", -1.0) + diverse_beam_groups = getattr(args, "diverse_beam_groups", -1) + diverse_beam_strength = getattr(args, "diverse_beam_strength", 0.5) + match_source_len = getattr(args, "match_source_len", False) + diversity_rate = getattr(args, "diversity_rate", -1) + constrained = getattr(args, "constraints", False) + if prefix_allowed_tokens_fn is None: + prefix_allowed_tokens_fn = getattr(args, "prefix_allowed_tokens_fn", None) + if ( + sum( + int(cond) + for cond in [ + sampling, + diverse_beam_groups > 0, + match_source_len, + diversity_rate > 0, + ] + ) + > 1 + ): + raise ValueError("Provided Search parameters are mutually exclusive.") + assert sampling_topk < 0 or sampling, "--sampling-topk requires --sampling" + assert sampling_topp < 0 or sampling, "--sampling-topp requires --sampling" + + if sampling: + search_strategy = search.Sampling( + self.target_dictionary, sampling_topk, sampling_topp + ) + elif diverse_beam_groups > 0: + search_strategy = search.DiverseBeamSearch( + self.target_dictionary, diverse_beam_groups, diverse_beam_strength + ) + elif match_source_len: + # this is useful for tagging applications where the output + # length should match the input length, so we hardcode the + # length constraints for simplicity + search_strategy = search.LengthConstrainedBeamSearch( + self.target_dictionary, + min_len_a=1, + min_len_b=0, + max_len_a=1, + max_len_b=0, + ) + elif diversity_rate > -1: + search_strategy = search.DiverseSiblingsSearch( + self.target_dictionary, diversity_rate + ) + elif constrained: + search_strategy = search.LexicallyConstrainedBeamSearch( + self.target_dictionary, args.constraints + ) + elif prefix_allowed_tokens_fn: + search_strategy = search.PrefixConstrainedBeamSearch( + self.target_dictionary, prefix_allowed_tokens_fn + ) + else: + search_strategy = search.BeamSearch(self.target_dictionary) + + extra_gen_cls_kwargs = extra_gen_cls_kwargs or {} + if seq_gen_cls is None: + if getattr(args, "print_alignment", False): + seq_gen_cls = SequenceGeneratorWithAlignment + extra_gen_cls_kwargs["print_alignment"] = args.print_alignment + else: + seq_gen_cls = SequenceGenerator + + return seq_gen_cls( + models, + self.target_dictionary, + beam_size=getattr(args, "beam", 5), + max_len_a=getattr(args, "max_len_a", 0), + max_len_b=getattr(args, "max_len_b", 200), + min_len=getattr(args, "min_len", 1), + normalize_scores=(not getattr(args, "unnormalized", False)), + len_penalty=getattr(args, "lenpen", 1), + unk_penalty=getattr(args, "unkpen", 0), + temperature=getattr(args, "temperature", 1.0), + match_source_len=getattr(args, "match_source_len", False), + no_repeat_ngram_size=getattr(args, "no_repeat_ngram_size", 0), + search_strategy=search_strategy, + **extra_gen_cls_kwargs, + ) + + def train_step( + self, sample, model, criterion, optimizer, update_num, ignore_grad=False + ): + """ + Do forward and backward, and return the loss as computed by *criterion* + for the given *model* and *sample*. + + Args: + sample (dict): the mini-batch. The format is defined by the + :class:`~fairseq.data.FairseqDataset`. + model (~fairseq.models.BaseFairseqModel): the model + criterion (~fairseq.criterions.FairseqCriterion): the criterion + optimizer (~fairseq.optim.FairseqOptimizer): the optimizer + update_num (int): the current update + ignore_grad (bool): multiply loss by 0 if this is set to True + + Returns: + tuple: + - the loss + - the sample size, which is used as the denominator for the + gradient + - logging outputs to display while training + """ + model.train() + model.set_num_updates(update_num) + with torch.autograd.profiler.record_function("forward"): + with torch.cuda.amp.autocast(enabled=(isinstance(optimizer, AMPOptimizer))): + loss, sample_size, logging_output = criterion(model, sample) + if ignore_grad: + loss *= 0 + with torch.autograd.profiler.record_function("backward"): + optimizer.backward(loss) + return loss, sample_size, logging_output + + def valid_step(self, sample, model, criterion): + model.eval() + with torch.no_grad(): + loss, sample_size, logging_output = criterion(model, sample) + return loss, sample_size, logging_output + + def optimizer_step(self, optimizer, model, update_num): + optimizer.step() + + def build_dataset_for_inference( + self, src_tokens: List[torch.Tensor], src_lengths: List[int], **kwargs + ) -> torch.utils.data.Dataset: + raise NotImplementedError + + def inference_step( + self, generator, models, sample, prefix_tokens=None, constraints=None + ): + with torch.no_grad(): + return generator.generate( + models, sample, prefix_tokens=prefix_tokens, constraints=constraints + ) + + def begin_epoch(self, epoch, model): + """Hook function called before the start of each epoch.""" + pass + + def begin_valid_epoch(self, epoch, model): + """Hook function called before the start of each validation epoch.""" + pass + + def aggregate_logging_outputs(self, logging_outputs, criterion): + """[deprecated] Aggregate logging outputs from data parallel training.""" + utils.deprecation_warning( + "The aggregate_logging_outputs API is deprecated. " + "Please use the reduce_metrics API instead." + ) + with metrics.aggregate() as agg: + self.reduce_metrics(logging_outputs, criterion) + return agg.get_smoothed_values() + + def reduce_metrics(self, logging_outputs, criterion): + """Aggregate logging outputs from data parallel training.""" + # backward compatibility for tasks that override aggregate_logging_outputs + base_func = FairseqTask.aggregate_logging_outputs + self_func = getattr(self, "aggregate_logging_outputs").__func__ + if self_func is not base_func: + utils.deprecation_warning( + "Tasks should implement the reduce_metrics API. " + "Falling back to deprecated aggregate_logging_outputs API." + ) + agg_logging_outputs = self.aggregate_logging_outputs( + logging_outputs, criterion + ) + for k, v in agg_logging_outputs.items(): + metrics.log_scalar(k, v) + return + + if not any("ntokens" in log for log in logging_outputs): + warnings.warn( + "ntokens not found in Criterion logging outputs, cannot log wpb or wps" + ) + else: + ntokens = sum(log.get("ntokens", 0) for log in logging_outputs) + metrics.log_scalar("wpb", ntokens, priority=180, round=1) + metrics.log_speed("wps", ntokens, priority=90, round=1) + + if not any("nsentences" in log for log in logging_outputs): + warnings.warn( + "nsentences not found in Criterion logging outputs, cannot log bsz" + ) + else: + nsentences = sum(log.get("nsentences", 0) for log in logging_outputs) + metrics.log_scalar("bsz", nsentences, priority=190, round=1) + + criterion.__class__.reduce_metrics(logging_outputs) + + def state_dict(self): + if self.state is not None: + return self.state.state_dict + return {} + + def load_state_dict(self, state_dict: Dict[str, Any]): + if self.state is not None: + self.state.merge_state_dict(state_dict) + + def max_positions(self): + """Return the max input length allowed by the task.""" + return None + + @property + def source_dictionary(self): + """Return the source :class:`~fairseq.data.Dictionary` (if applicable + for this task).""" + raise NotImplementedError + + @property + def target_dictionary(self): + """Return the target :class:`~fairseq.data.Dictionary` (if applicable + for this task).""" + raise NotImplementedError + + def build_tokenizer(self, args): + """Build the pre-tokenizer for this task.""" + return encoders.build_tokenizer(args) + + def build_bpe(self, args): + """Build the tokenizer for this task.""" + return encoders.build_bpe(args) + + def get_interactive_tokens_and_lengths(self, lines, encode_fn): + tokens = [ + self.source_dictionary.encode_line( + encode_fn(src_str), add_if_not_exist=False + ).long() + for src_str in lines + ] + lengths = [t.numel() for t in tokens] + return tokens, lengths + + +class LegacyFairseqTask(FairseqTask): + def __init__(self, args: Namespace): + super().__init__(None) + self.args = args + self.datasets = {} + self.dataset_to_epoch_iter = {} + + @classmethod + def setup_task(cls, args: Namespace, **kwargs): + """Setup the task (e.g., load dictionaries). + + Args: + args (argparse.Namespace): parsed command-line arguments + """ + return cls(args, **kwargs) + + def has_sharded_data(self, split): + return os.pathsep in getattr(self.args, "data", "") + + def build_model(self, args: Namespace, from_checkpoint=False): + """ + Build the :class:`~fairseq.models.BaseFairseqModel` instance for this + task. + + Args: + args (argparse.Namespace): parsed command-line arguments + + Returns: + a :class:`~fairseq.models.BaseFairseqModel` instance + """ + from fairseq import models, quantization_utils + + model = models.build_model(args, self, from_checkpoint) + model = quantization_utils.quantize_model_scalar(model, args) + return model + + def build_criterion(self, args: Namespace): + """ + Build the :class:`~fairseq.criterions.FairseqCriterion` instance for + this task. + + Args: + args (argparse.Namespace): parsed command-line arguments + + Returns: + a :class:`~fairseq.criterions.FairseqCriterion` instance + """ + from fairseq import criterions + + return criterions.build_criterion(args, self) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/frm_text_to_speech.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/frm_text_to_speech.py new file mode 100644 index 00000000..667f5f8e --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/frm_text_to_speech.py @@ -0,0 +1,55 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +from fairseq.data.audio.frm_text_to_speech_dataset import FrmTextToSpeechDatasetCreator +from fairseq.tasks import register_task +from fairseq.tasks.text_to_speech import TextToSpeechTask + + +logging.basicConfig( + format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + level=logging.INFO, +) +logger = logging.getLogger(__name__) + + +@register_task("frm_text_to_speech") +class FrmTextToSpeechTask(TextToSpeechTask): + @staticmethod + def add_args(parser): + TextToSpeechTask.add_args(parser) + parser.add_argument("--do_chunk", action="store_true", help="train on chunks") + parser.add_argument("--chunk_bound", default=-1, type=int) + parser.add_argument("--chunk_init", default=50, type=int) + parser.add_argument("--chunk_incr", default=5, type=int) + parser.add_argument("--add_eos", action="store_true") + parser.add_argument("--dedup", action="store_true") + parser.add_argument("--ref_fpu", default=-1, type=float) + + def load_dataset(self, split, **unused_kwargs): + is_train_split = split.startswith("train") + pre_tokenizer = self.build_tokenizer(self.args) + bpe_tokenizer = self.build_bpe(self.args) + self.datasets[split] = FrmTextToSpeechDatasetCreator.from_tsv( + self.args.data, + self.data_cfg, + split, + self.src_dict, + pre_tokenizer, + bpe_tokenizer, + is_train_split=is_train_split, + n_frames_per_step=self.args.n_frames_per_step, + speaker_to_id=self.speaker_to_id, + do_chunk=self.args.do_chunk, + chunk_bound=self.args.chunk_bound, + chunk_init=self.args.chunk_init, + chunk_incr=self.args.chunk_incr, + add_eos=self.args.add_eos, + dedup=self.args.dedup, + ref_fpu=self.args.ref_fpu, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/hubert_pretraining.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/hubert_pretraining.py new file mode 100644 index 00000000..1a3605f1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/hubert_pretraining.py @@ -0,0 +1,191 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + +import logging +import os +import sys +from typing import Dict, List, Optional, Tuple + +import numpy as np + +from dataclasses import dataclass, field +from fairseq.data import Dictionary, HubertDataset +from fairseq.dataclass.configs import FairseqDataclass +from fairseq.tasks import register_task +from fairseq.tasks.fairseq_task import FairseqTask +from omegaconf import MISSING + +logger = logging.getLogger(__name__) + + +class LabelEncoder(object): + def __init__(self, dictionary: Dictionary) -> None: + self.dictionary = dictionary + + def __call__(self, label: str) -> List[str]: + return self.dictionary.encode_line( + label, + append_eos=False, + add_if_not_exist=False, + ) + + +@dataclass +class HubertPretrainingConfig(FairseqDataclass): + data: str = field(default=MISSING, metadata={"help": "path to data directory"}) + fine_tuning: bool = field( + default=False, metadata={"help": "set to true if fine-tuning Hubert"} + ) + labels: List[str] = field( + default_factory=lambda: ["ltr"], + metadata={ + "help": ( + "extension of the label files to load, frame-level labels for" + " pre-training, and sequence-level label for fine-tuning" + ) + }, + ) + label_dir: Optional[str] = field( + default=None, + metadata={ + "help": "if set, looks for labels in this directory instead", + }, + ) + label_rate: float = field( + default=-1.0, + metadata={"help": "label frame rate. -1.0 for sequence label"}, + ) + sample_rate: int = field( + default=16_000, + metadata={ + "help": "target sample rate. audio files will be up/down " + "sampled to this rate" + }, + ) + normalize: bool = field( + default=False, + metadata={"help": "if set, normalizes input to have 0 mean and unit variance"}, + ) + enable_padding: bool = field( + default=False, + metadata={"help": "pad shorter samples instead of cropping"}, + ) + max_keep_size: Optional[int] = field( + default=None, + metadata={"help": "exclude sample longer than this"}, + ) + max_sample_size: Optional[int] = field( + default=None, + metadata={"help": "max sample size to crop to for batching"}, + ) + min_sample_size: Optional[int] = field( + default=None, + metadata={"help": "min sample size to crop to for batching"}, + ) + single_target: Optional[bool] = field( + default=False, + metadata={ + "help": "if set, AddTargetDatasets outputs same keys " "as AddTargetDataset" + }, + ) + random_crop: Optional[bool] = field( + default=True, + metadata={"help": "always crop from the beginning if false"}, + ) + pad_audio: Optional[bool] = field( + default=False, + metadata={"help": "pad audio to the longest one in the batch if true"}, + ) + + +@register_task("hubert_pretraining", dataclass=HubertPretrainingConfig) +class HubertPretrainingTask(FairseqTask): + + cfg: HubertPretrainingConfig + + def __init__( + self, + cfg: HubertPretrainingConfig, + ) -> None: + super().__init__(cfg) + + logger.info(f"current directory is {os.getcwd()}") + logger.info(f"HubertPretrainingTask Config {cfg}") + + self.cfg = cfg + self.fine_tuning = cfg.fine_tuning + + if cfg.fine_tuning: + self.state.add_factory("target_dictionary", self.load_dictionaries) + else: + self.state.add_factory("dictionaries", self.load_dictionaries) + + self.blank_symbol = "" + + @property + def source_dictionary(self) -> Optional[Dictionary]: + return None + + @property + def target_dictionary(self) -> Optional[Dictionary]: + return self.state.target_dictionary + + @property + def dictionaries(self) -> List[Dictionary]: + return self.state.dictionaries + + @classmethod + def setup_task( + cls, cfg: HubertPretrainingConfig, **kwargs + ) -> "HubertPretrainingTask": + return cls(cfg) + + def load_dictionaries(self): + label_dir = self.cfg.data if self.cfg.label_dir is None else self.cfg.label_dir + dictionaries = [ + Dictionary.load(f"{label_dir}/dict.{label}.txt") + for label in self.cfg.labels + ] + return dictionaries[0] if self.cfg.fine_tuning else dictionaries + + def get_label_dir(self) -> str: + if self.cfg.label_dir is None: + return self.cfg.data + return self.cfg.label_dir + + def load_dataset(self, split: str, **kwargs) -> None: + manifest = f"{self.cfg.data}/{split}.tsv" + dicts = [self.target_dictionary] if self.cfg.fine_tuning else self.dictionaries + pad_list = [dict.pad() for dict in dicts] + eos_list = [dict.eos() for dict in dicts] + procs = [LabelEncoder(dict) for dict in dicts] + paths = [f"{self.get_label_dir()}/{split}.{l}" for l in self.cfg.labels] + + # hubert v1: pad_audio=True, random_crop=False; + self.datasets[split] = HubertDataset( + manifest, + sample_rate=self.cfg.sample_rate, + label_paths=paths, + label_rates=self.cfg.label_rate, + pad_list=pad_list, + eos_list=eos_list, + label_processors=procs, + max_keep_sample_size=self.cfg.max_keep_size, + min_keep_sample_size=self.cfg.min_sample_size, + max_sample_size=self.cfg.max_sample_size, + pad_audio=self.cfg.pad_audio, + normalize=self.cfg.normalize, + store_labels=False, + random_crop=self.cfg.random_crop, + single_target=self.cfg.single_target, + ) + + def max_positions(self) -> Tuple[int, int]: + return (sys.maxsize, sys.maxsize) + + def filter_indices_by_size(self, indices: np.array, *args, **kwargs) -> np.array: + return indices diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/language_modeling.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/language_modeling.py new file mode 100644 index 00000000..44d5324b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/language_modeling.py @@ -0,0 +1,383 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +from dataclasses import dataclass, field +from typing import Optional + +import numpy as np +import torch +from fairseq import utils +from fairseq.data import ( + AppendTokenDataset, + Dictionary, + IdDataset, + LMContextWindowDataset, + MonolingualDataset, + NestedDictionaryDataset, + NumelDataset, + PadDataset, + PrependTokenDataset, + StripTokenDataset, + TokenBlockDataset, + TruncatedDictionary, + data_utils, +) +from fairseq.data.indexed_dataset import get_available_dataset_impl +from fairseq.data.shorten_dataset import maybe_shorten_dataset +from fairseq.dataclass import ChoiceEnum, FairseqDataclass +from fairseq.tasks import LegacyFairseqTask, register_task +from omegaconf import II + + +SAMPLE_BREAK_MODE_CHOICES = ChoiceEnum(["none", "complete", "complete_doc", "eos"]) +SHORTEN_METHOD_CHOICES = ChoiceEnum(["none", "truncate", "random_crop"]) +logger = logging.getLogger(__name__) + + +@dataclass +class LanguageModelingConfig(FairseqDataclass): + data: Optional[str] = field( + default=None, metadata={"help": "path to data directory"} + ) + sample_break_mode: SAMPLE_BREAK_MODE_CHOICES = field( + default="none", + metadata={ + "help": 'If omitted or "none", fills each sample with tokens-per-sample ' + 'tokens. If set to "complete", splits samples only at the end ' + "of sentence, but may include multiple sentences per sample. " + '"complete_doc" is similar but respects doc boundaries. ' + 'If set to "eos", includes only one sentence per sample.' + }, + ) + tokens_per_sample: int = field( + default=1024, + metadata={"help": "max number of tokens per sample for LM dataset"}, + ) + output_dictionary_size: int = field( + default=-1, metadata={"help": "limit the size of output dictionary"} + ) + self_target: bool = field(default=False, metadata={"help": "include self target"}) + future_target: bool = field( + default=False, metadata={"help": "include future target"} + ) + past_target: bool = field(default=False, metadata={"help": "include past target"}) + add_bos_token: bool = field( + default=False, metadata={"help": "prepend beginning of sentence token ()"} + ) + max_target_positions: Optional[int] = field( + default=None, metadata={"help": "max number of tokens in the target sequence"} + ) + shorten_method: SHORTEN_METHOD_CHOICES = field( + default="none", + metadata={ + "help": "if not none, shorten sequences that exceed --tokens-per-sample" + }, + ) + shorten_data_split_list: str = field( + default="", + metadata={ + "help": "comma-separated list of dataset splits to apply shortening to, " + 'e.g., "train,valid" (default: all dataset splits)' + }, + ) + pad_to_fixed_length: Optional[bool] = field( + default=False, + metadata={"help": "pad to fixed length"}, + ) + pad_to_fixed_bsz: Optional[bool] = field( + default=False, + metadata={"help": "boolean to pad to fixed batch size"}, + ) + + # TODO common vars below add to parent + seed: int = II("common.seed") + batch_size: Optional[int] = II("dataset.batch_size") + batch_size_valid: Optional[int] = II("dataset.batch_size_valid") + dataset_impl: Optional[ChoiceEnum(get_available_dataset_impl())] = II( + "dataset.dataset_impl" + ) + data_buffer_size: int = II("dataset.data_buffer_size") + tpu: bool = II("common.tpu") + use_plasma_view: bool = II("common.use_plasma_view") + plasma_path: str = II("common.plasma_path") + + +@register_task("language_modeling", dataclass=LanguageModelingConfig) +class LanguageModelingTask(LegacyFairseqTask): + """ + Train a language model. + + Args: + dictionary (~fairseq.data.Dictionary): the dictionary for the input of + the language model + output_dictionary (~fairseq.data.Dictionary): the dictionary for the + output of the language model. In most cases it will be the same as + *dictionary*, but could possibly be a more limited version of the + dictionary (if ``--output-dictionary-size`` is used). + targets (List[str]): list of the target types that the language model + should predict. Can be one of "self", "future", and "past". + Defaults to "future". + + .. note:: + + The language modeling task is compatible with :mod:`fairseq-train`, + :mod:`fairseq-generate`, :mod:`fairseq-interactive` and + :mod:`fairseq-eval-lm`. + + The language modeling task provides the following additional command-line + arguments: + + .. argparse:: + :ref: fairseq.tasks.language_modeling_parser + :prog: + """ + + def __init__(self, args, dictionary, output_dictionary=None, targets=None): + super().__init__(args) + self.dictionary = dictionary + self.output_dictionary = output_dictionary or dictionary + + if targets is None: + targets = ["future"] + self.targets = targets + + @classmethod + def setup_dictionary(cls, args, **kwargs): + dictionary = None + output_dictionary = None + if args.data: + paths = utils.split_paths(args.data) + assert len(paths) > 0 + dictionary = Dictionary.load(os.path.join(paths[0], "dict.txt")) + logger.info("dictionary: {} types".format(len(dictionary))) + output_dictionary = dictionary + if args.output_dictionary_size >= 0: + output_dictionary = TruncatedDictionary( + dictionary, args.output_dictionary_size + ) + return (dictionary, output_dictionary) + + @classmethod + def setup_task(cls, args, **kwargs): + """Setup the task (e.g., load dictionaries). + + Args: + args (argparse.Namespace): parsed command-line arguments + """ + dictionary, output_dictionary = cls.setup_dictionary(args, **kwargs) + + # upgrade old checkpoints + if getattr(args, "exclude_self_target", False): + args.self_target = False + + targets = [] + if getattr(args, "self_target", False): + targets.append("self") + if getattr(args, "future_target", False): + targets.append("future") + if getattr(args, "past_target", False): + targets.append("past") + if len(targets) == 0: + # standard language modeling + targets = ["future"] + + return cls(args, dictionary, output_dictionary, targets=targets) + + def build_model(self, args, from_checkpoint=False): + model = super().build_model(args, from_checkpoint) + for target in self.targets: + if target not in model.supported_targets: + raise ValueError( + "Unsupported language modeling target: {}".format(target) + ) + + return model + + def load_dataset( + self, split: str, epoch=1, combine=False, **kwargs + ) -> MonolingualDataset: + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, valid1, test) + """ + paths = utils.split_paths(self.args.data) + assert len(paths) > 0 + + data_path = paths[(epoch - 1) % len(paths)] + split_path = os.path.join(data_path, split) + + # each process has its own copy of the raw data (likely to be an np.memmap) + dataset = data_utils.load_indexed_dataset( + split_path, self.dictionary, self.args.dataset_impl, combine=combine + ) + if dataset is None: + raise FileNotFoundError(f"Dataset not found: {split} ({split_path})") + + dataset = maybe_shorten_dataset( + dataset, + split, + self.args.shorten_data_split_list, + self.args.shorten_method, + self.args.tokens_per_sample, + self.args.seed, + ) + dataset = TokenBlockDataset( + dataset, + dataset.sizes, + self.args.tokens_per_sample, + pad=self.dictionary.pad(), + eos=self.dictionary.eos(), + break_mode=self.args.sample_break_mode, + include_targets=True, + use_plasma_view=self.args.use_plasma_view, + split_path=split_path, + plasma_path=self.args.plasma_path, + ) + + add_eos_for_other_targets = ( + self.args.sample_break_mode is not None + and self.args.sample_break_mode != "none" + ) + fixed_pad_length = None + if self.args.pad_to_fixed_length: + fixed_pad_length = self.args.tokens_per_sample + + pad_to_bsz = None + if self.args.pad_to_fixed_bsz: + pad_to_bsz = ( + self.args.batch_size_valid if "valid" in split else self.args.batch_size + ) + + self.datasets[split] = MonolingualDataset( + dataset=dataset, + sizes=dataset.sizes, + src_vocab=self.dictionary, + tgt_vocab=self.output_dictionary, + add_eos_for_other_targets=add_eos_for_other_targets, + shuffle=True, + targets=self.targets, + add_bos_token=self.args.add_bos_token, + fixed_pad_length=fixed_pad_length, + pad_to_bsz=pad_to_bsz, + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, **kwargs): + """ + Generate batches for inference. We prepend an eos token to src_tokens + (or bos if `--add-bos-token` is set) and we append a to target. + This is convenient both for generation with a prefix and LM scoring. + """ + dataset = StripTokenDataset( + TokenBlockDataset( + src_tokens, + src_lengths, + block_size=None, # ignored for "eos" break mode + pad=self.source_dictionary.pad(), + eos=self.source_dictionary.eos(), + break_mode="eos", + ), + # remove eos from (end of) target sequence + self.source_dictionary.eos(), + ) + src_dataset = PrependTokenDataset( + dataset, + token=( + self.source_dictionary.bos() + if getattr(self.args, "add_bos_token", False) + else self.source_dictionary.eos() + ), + ) + tgt_dataset = AppendTokenDataset(dataset, token=self.source_dictionary.pad()) + return NestedDictionaryDataset( + { + "id": IdDataset(), + "net_input": { + "src_tokens": PadDataset( + src_dataset, + pad_idx=self.source_dictionary.pad(), + left_pad=False, + ), + "src_lengths": NumelDataset(src_dataset, reduce=False), + }, + "target": PadDataset( + tgt_dataset, pad_idx=self.source_dictionary.pad(), left_pad=False + ), + }, + sizes=[np.array(src_lengths)], + ) + + def inference_step( + self, generator, models, sample, prefix_tokens=None, constraints=None + ): + with torch.no_grad(): + # Generation will always be conditioned on bos_token + if getattr(self.args, "add_bos_token", False): + bos_token = self.source_dictionary.bos() + else: + bos_token = self.source_dictionary.eos() + + if constraints is not None: + raise NotImplementedError( + "Constrained decoding with the language_modeling task is not supported" + ) + + # SequenceGenerator doesn't use src_tokens directly, we need to + # pass the `prefix_tokens` argument instead + if prefix_tokens is None and sample["net_input"]["src_tokens"].nelement(): + prefix_tokens = sample["net_input"]["src_tokens"] + if prefix_tokens[:, 0].eq(bos_token).all(): + prefix_tokens = prefix_tokens[:, 1:] + + return generator.generate( + models, sample, prefix_tokens=prefix_tokens, bos_token=bos_token + ) + + def eval_lm_dataloader( + self, + dataset, + max_tokens: Optional[int] = 36000, + batch_size: Optional[int] = None, + max_positions: Optional[int] = None, + num_shards: int = 1, + shard_id: int = 0, + num_workers: int = 1, + data_buffer_size: int = 10, + # ensures that every evaluated token has access to a context of at least + # this size, if possible + context_window: int = 0, + ): + if context_window > 0: + dataset = LMContextWindowDataset( + dataset=dataset, + tokens_per_sample=self.args.tokens_per_sample, + context_window=context_window, + pad_idx=self.source_dictionary.pad(), + ) + return self.get_batch_iterator( + dataset=dataset, + max_tokens=max_tokens, + max_sentences=batch_size, + max_positions=max_positions, + ignore_invalid_inputs=True, + num_shards=num_shards, + shard_id=shard_id, + num_workers=num_workers, + data_buffer_size=data_buffer_size, + ).next_epoch_itr(shuffle=False) + + @property + def source_dictionary(self): + """Return the :class:`~fairseq.data.Dictionary` for the language + model.""" + return self.dictionary + + @property + def target_dictionary(self): + """Return the :class:`~fairseq.data.Dictionary` for the language + model.""" + return self.output_dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/legacy_masked_lm.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/legacy_masked_lm.py new file mode 100644 index 00000000..97549765 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/legacy_masked_lm.py @@ -0,0 +1,152 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import itertools +import logging +import os + +import numpy as np +from fairseq import tokenizer, utils +from fairseq.data import ConcatDataset, Dictionary, data_utils, indexed_dataset +from fairseq.data.legacy.block_pair_dataset import BlockPairDataset +from fairseq.data.legacy.masked_lm_dataset import MaskedLMDataset +from fairseq.data.legacy.masked_lm_dictionary import BertDictionary +from fairseq.tasks import LegacyFairseqTask, register_task + + +logger = logging.getLogger(__name__) + + +@register_task("legacy_masked_lm") +class LegacyMaskedLMTask(LegacyFairseqTask): + """ + Task for training Masked LM (BERT) model. + Args: + dictionary (Dictionary): the dictionary for the input of the task + """ + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + parser.add_argument( + "data", + help="colon separated path to data directories list, \ + will be iterated upon during epochs in round-robin manner", + ) + parser.add_argument( + "--tokens-per-sample", + default=512, + type=int, + help="max number of total tokens over all segments" + " per sample for BERT dataset", + ) + parser.add_argument( + "--break-mode", default="doc", type=str, help="mode for breaking sentence" + ) + parser.add_argument("--shuffle-dataset", action="store_true", default=False) + + def __init__(self, args, dictionary): + super().__init__(args) + self.dictionary = dictionary + self.seed = args.seed + + @classmethod + def load_dictionary(cls, filename): + return BertDictionary.load(filename) + + @classmethod + def build_dictionary( + cls, filenames, workers=1, threshold=-1, nwords=-1, padding_factor=8 + ): + d = BertDictionary() + for filename in filenames: + Dictionary.add_file_to_dictionary( + filename, d, tokenizer.tokenize_line, workers + ) + d.finalize(threshold=threshold, nwords=nwords, padding_factor=padding_factor) + return d + + @property + def target_dictionary(self): + return self.dictionary + + @classmethod + def setup_task(cls, args, **kwargs): + """Setup the task.""" + paths = utils.split_paths(args.data) + assert len(paths) > 0 + dictionary = BertDictionary.load(os.path.join(paths[0], "dict.txt")) + logger.info("dictionary: {} types".format(len(dictionary))) + + return cls(args, dictionary) + + def load_dataset(self, split, epoch=1, combine=False): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + loaded_datasets = [] + + paths = utils.split_paths(self.args.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + logger.info("data_path", data_path) + + for k in itertools.count(): + split_k = split + (str(k) if k > 0 else "") + path = os.path.join(data_path, split_k) + ds = indexed_dataset.make_dataset( + path, + impl=self.args.dataset_impl, + fix_lua_indexing=True, + dictionary=self.dictionary, + ) + + if ds is None: + if k > 0: + break + else: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, data_path) + ) + + with data_utils.numpy_seed(self.seed + k): + loaded_datasets.append( + BlockPairDataset( + ds, + self.dictionary, + ds.sizes, + self.args.tokens_per_sample, + break_mode=self.args.break_mode, + doc_break_size=1, + ) + ) + + logger.info( + "{} {} {} examples".format(data_path, split_k, len(loaded_datasets[-1])) + ) + + if not combine: + break + + if len(loaded_datasets) == 1: + dataset = loaded_datasets[0] + sizes = dataset.sizes + else: + dataset = ConcatDataset(loaded_datasets) + sizes = np.concatenate([ds.sizes for ds in loaded_datasets]) + + self.datasets[split] = MaskedLMDataset( + dataset=dataset, + sizes=sizes, + vocab=self.dictionary, + pad_idx=self.dictionary.pad(), + mask_idx=self.dictionary.mask(), + classif_token_idx=self.dictionary.cls(), + sep_token_idx=self.dictionary.sep(), + shuffle=self.args.shuffle_dataset, + seed=self.seed, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/masked_lm.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/masked_lm.py new file mode 100644 index 00000000..6393ee48 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/masked_lm.py @@ -0,0 +1,270 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +from dataclasses import dataclass, field + +import numpy as np +from omegaconf import II, MISSING, OmegaConf + +from fairseq import utils +from fairseq.data import ( + Dictionary, + IdDataset, + MaskTokensDataset, + NestedDictionaryDataset, + NumelDataset, + NumSamplesDataset, + PrependTokenDataset, + RightPadDataset, + SortDataset, + TokenBlockDataset, + data_utils, +) +from fairseq.data.encoders.utils import get_whole_word_mask +from fairseq.data.shorten_dataset import maybe_shorten_dataset +from fairseq.dataclass import FairseqDataclass +from fairseq.tasks import FairseqTask, register_task + +from .language_modeling import SAMPLE_BREAK_MODE_CHOICES, SHORTEN_METHOD_CHOICES + +logger = logging.getLogger(__name__) + + +@dataclass +class MaskedLMConfig(FairseqDataclass): + data: str = field( + default=MISSING, + metadata={ + "help": "colon separated path to data directories list, \ + will be iterated upon during epochs in round-robin manner" + }, + ) + sample_break_mode: SAMPLE_BREAK_MODE_CHOICES = field( + default="none", + metadata={ + "help": 'If omitted or "none", fills each sample with tokens-per-sample ' + 'tokens. If set to "complete", splits samples only at the end ' + "of sentence, but may include multiple sentences per sample. " + '"complete_doc" is similar but respects doc boundaries. ' + 'If set to "eos", includes only one sentence per sample.' + }, + ) + tokens_per_sample: int = field( + default=1024, + metadata={"help": "max number of tokens per sample for LM dataset"}, + ) + mask_prob: float = field( + default=0.15, + metadata={"help": "probability of replacing a token with mask"}, + ) + leave_unmasked_prob: float = field( + default=0.1, + metadata={"help": "probability that a masked token is unmasked"}, + ) + random_token_prob: float = field( + default=0.1, + metadata={"help": "probability of replacing a token with a random token"}, + ) + freq_weighted_replacement: bool = field( + default=False, + metadata={"help": "sample random replacement words based on word frequencies"}, + ) + mask_whole_words: bool = field( + default=False, + metadata={"help": "mask whole words; you may also want to set --bpe"}, + ) + mask_multiple_length: int = field( + default=1, + metadata={"help": "repeat the mask indices multiple times"}, + ) + mask_stdev: float = field( + default=0.0, + metadata={"help": "stdev of the mask length"}, + ) + shorten_method: SHORTEN_METHOD_CHOICES = field( + default="none", + metadata={ + "help": "if not none, shorten sequences that exceed --tokens-per-sample" + }, + ) + shorten_data_split_list: str = field( + default="", + metadata={ + "help": "comma-separated list of dataset splits to apply shortening to, " + 'e.g., "train,valid" (default: all dataset splits)' + }, + ) + seed: int = II("common.seed") + + include_target_tokens: bool = field( + default=False, + metadata={ + "help": "include target tokens in model input. this is used for data2vec" + }, + ) + + +@register_task("masked_lm", dataclass=MaskedLMConfig) +class MaskedLMTask(FairseqTask): + + cfg: MaskedLMConfig + + """Task for training masked language models (e.g., BERT, RoBERTa).""" + + def __init__(self, cfg: MaskedLMConfig, dictionary): + super().__init__(cfg) + self.dictionary = dictionary + + # add mask token + self.mask_idx = dictionary.add_symbol("") + + @classmethod + def setup_task(cls, cfg: MaskedLMConfig, **kwargs): + paths = utils.split_paths(cfg.data) + assert len(paths) > 0 + dictionary = Dictionary.load(os.path.join(paths[0], "dict.txt")) + logger.info("dictionary: {} types".format(len(dictionary))) + return cls(cfg, dictionary) + + def _load_dataset_split(self, split, epoch, combine): + paths = utils.split_paths(self.cfg.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + split_path = os.path.join(data_path, split) + + dataset = data_utils.load_indexed_dataset( + split_path, + self.source_dictionary, + combine=combine, + ) + if dataset is None: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, split_path) + ) + + dataset = maybe_shorten_dataset( + dataset, + split, + self.cfg.shorten_data_split_list, + self.cfg.shorten_method, + self.cfg.tokens_per_sample, + self.cfg.seed, + ) + + # create continuous blocks of tokens + dataset = TokenBlockDataset( + dataset, + dataset.sizes, + self.cfg.tokens_per_sample - 1, # one less for + pad=self.source_dictionary.pad(), + eos=self.source_dictionary.eos(), + break_mode=self.cfg.sample_break_mode, + ) + logger.info("loaded {} blocks from: {}".format(len(dataset), split_path)) + + # prepend beginning-of-sentence token (, equiv. to [CLS] in BERT) + return PrependTokenDataset(dataset, self.source_dictionary.bos()) + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + dataset = self._load_dataset_split(split, epoch, combine) + + # create masked input and targets + mask_whole_words = ( + get_whole_word_mask(self.args, self.source_dictionary) + if self.cfg.mask_whole_words + else None + ) + + src_dataset, tgt_dataset = MaskTokensDataset.apply_mask( + dataset, + self.source_dictionary, + pad_idx=self.source_dictionary.pad(), + mask_idx=self.mask_idx, + seed=self.cfg.seed, + mask_prob=self.cfg.mask_prob, + leave_unmasked_prob=self.cfg.leave_unmasked_prob, + random_token_prob=self.cfg.random_token_prob, + freq_weighted_replacement=self.cfg.freq_weighted_replacement, + mask_whole_words=mask_whole_words, + mask_multiple_length=self.cfg.mask_multiple_length, + mask_stdev=self.cfg.mask_stdev, + ) + + with data_utils.numpy_seed(self.cfg.seed): + shuffle = np.random.permutation(len(src_dataset)) + + target_dataset = RightPadDataset( + tgt_dataset, + pad_idx=self.source_dictionary.pad(), + ) + + input_dict = { + "src_tokens": RightPadDataset( + src_dataset, + pad_idx=self.source_dictionary.pad(), + ), + "src_lengths": NumelDataset(src_dataset, reduce=False), + } + if self.cfg.include_target_tokens: + input_dict["target_tokens"] = target_dataset + + self.datasets[split] = SortDataset( + NestedDictionaryDataset( + { + "id": IdDataset(), + "net_input": input_dict, + "target": target_dataset, + "nsentences": NumSamplesDataset(), + "ntokens": NumelDataset(src_dataset, reduce=True), + }, + sizes=[src_dataset.sizes], + ), + sort_order=[ + shuffle, + src_dataset.sizes, + ], + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, sort=True): + src_dataset = RightPadDataset( + TokenBlockDataset( + src_tokens, + src_lengths, + self.cfg.tokens_per_sample - 1, # one less for + pad=self.source_dictionary.pad(), + eos=self.source_dictionary.eos(), + break_mode="eos", + ), + pad_idx=self.source_dictionary.pad(), + ) + src_dataset = PrependTokenDataset(src_dataset, self.source_dictionary.bos()) + src_dataset = NestedDictionaryDataset( + { + "id": IdDataset(), + "net_input": { + "src_tokens": src_dataset, + "src_lengths": NumelDataset(src_dataset, reduce=False), + }, + }, + sizes=src_lengths, + ) + if sort: + src_dataset = SortDataset(src_dataset, sort_order=[src_lengths]) + return src_dataset + + @property + def source_dictionary(self): + return self.dictionary + + @property + def target_dictionary(self): + return self.dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_denoising.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_denoising.py new file mode 100644 index 00000000..8226d950 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_denoising.py @@ -0,0 +1,254 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os + +import numpy as np + +from fairseq.data import ( + AppendTokenDataset, + ConcatDataset, + DenoisingDataset, + Dictionary, + PrependTokenDataset, + ResamplingDataset, + SortDataset, + TokenBlockDataset, + data_utils, +) +from fairseq.data.encoders.utils import get_whole_word_mask +from fairseq.tasks import register_task + +from .denoising import DenoisingTask + +logger = logging.getLogger(__name__) + + +@register_task("multilingual_denoising") +class MultilingualDenoisingTask(DenoisingTask): + @staticmethod + def add_args(parser): + DenoisingTask.add_args(parser) + parser.add_argument( + "--multilang-sampling-alpha", + type=float, + default=1.0, + help="smoothing alpha for sample ratios across multiple datasets", + ) + parser.add_argument("--add-lang-token", default=False, action="store_true") + parser.add_argument( + "--langs", type=str, help="language ids we are considering", default=None + ) + parser.add_argument( + "--no-whole-word-mask-langs", + type=str, + default="", + metavar="N", + help="languages without spacing between words dont support whole word masking", + ) + + @classmethod + def setup_task(cls, args, **kwargs): + """Setup the task.""" + paths = args.data.split(":") + assert len(paths) > 0 + dictionary = Dictionary.load(os.path.join(paths[0], "dict.txt")) + + data_path = paths[0] + if args.langs is None: + languages = sorted( + [ + name + for name in os.listdir(data_path) + if os.path.isdir(os.path.join(data_path, name)) + ] + ) + else: + languages = args.langs.split(",") + + if args.add_lang_token: + for lang in languages: + dictionary.add_symbol("[{}]".format(lang)) + + logger.info("dictionary: {} types".format(len(dictionary))) + if not hasattr(args, "shuffle_instance"): + args.shuffle_instance = False + return cls(args, dictionary) + + def __init__(self, args, dictionary): + super().__init__(args, dictionary) + self.dictionary = dictionary + self.seed = args.seed + + # add mask token + self.mask_idx = self.dictionary.add_symbol("") + self.langs = args.langs + self.args = args + + def _get_sample_prob(self, dataset_lens): + """ + Get smoothed sampling porbability by languages. This helps low resource + languages by upsampling them. + """ + prob = dataset_lens / dataset_lens.sum() + smoothed_prob = prob**self.args.multilang_sampling_alpha + smoothed_prob = smoothed_prob / smoothed_prob.sum() + return smoothed_prob + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + paths = self.args.data.split(":") + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + split_path = os.path.join(data_path, split) + + if self.langs is None: + languages = sorted( + [ + name + for name in os.listdir(data_path) + if os.path.isdir(os.path.join(data_path, name)) + ] + ) + else: + languages = self.langs.split(",") + for name in languages: + p = os.path.join(data_path, name) + assert os.path.exists(p), "data not found: {}".format(p) + + logger.info("Training on {0} languages: {1}".format(len(languages), languages)) + logger.info( + "Language to id mapping: ", {lang: id for id, lang in enumerate(languages)} + ) + + mask_whole_words = get_whole_word_mask(self.args, self.dictionary) + language_without_segmentations = self.args.no_whole_word_mask_langs.split(",") + lang_datasets = [] + for language in languages: + split_path = os.path.join(data_path, language, split) + + dataset = data_utils.load_indexed_dataset( + split_path, + self.source_dictionary, + self.args.dataset_impl, + combine=combine, + ) + if dataset is None: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, split_path) + ) + + end_token = ( + self.source_dictionary.index("[{}]".format(language)) + if self.args.add_lang_token + else self.source_dictionary.eos() + ) + + # create continuous blocks of tokens + dataset = TokenBlockDataset( + dataset, + dataset.sizes, + self.args.tokens_per_sample - 2, # one less for + pad=self.source_dictionary.pad(), + eos=end_token, + break_mode=self.args.sample_break_mode, + ) + logger.info("loaded {} blocks from: {}".format(len(dataset), split_path)) + + # prepend beginning-of-sentence token (, equiv. to [CLS] in BERT) + dataset = PrependTokenDataset(dataset, self.source_dictionary.bos()) + dataset = AppendTokenDataset(dataset, end_token) + + lang_mask_whole_words = ( + mask_whole_words + if language not in language_without_segmentations + else None + ) + lang_dataset = DenoisingDataset( + dataset, + dataset.sizes, + self.dictionary, + self.mask_idx, + lang_mask_whole_words, + shuffle=self.args.shuffle_instance, + seed=self.seed, + args=self.args, + eos=None + if not self.args.add_lang_token + else self.source_dictionary.index("[{}]".format(language)), + ) + lang_datasets.append(lang_dataset) + + dataset_lengths = np.array( + [len(d) for d in lang_datasets], + dtype=float, + ) + logger.info( + "loaded total {} blocks for all languages".format( + int(dataset_lengths.sum()), + ) + ) + if split == self.args.train_subset: + # For train subset, additionally up or down sample languages. + sample_probs = self._get_sample_prob(dataset_lengths) + logger.info( + "Sample probability by language: {}".format( + { + lang: "{0:.4f}".format(sample_probs[id]) + for id, lang in enumerate(languages) + } + ) + ) + size_ratio = (sample_probs * dataset_lengths.sum()) / dataset_lengths + logger.info( + "Up/Down Sampling ratio by language: {}".format( + { + lang: "{0:.2f}".format(size_ratio[id]) + for id, lang in enumerate(languages) + } + ) + ) + + resampled_lang_datasets = [ + ResamplingDataset( + lang_datasets[i], + size_ratio=size_ratio[i], + seed=self.args.seed, + epoch=epoch, + replace=size_ratio[i] >= 1.0, + ) + for i, d in enumerate(lang_datasets) + ] + dataset = ConcatDataset( + resampled_lang_datasets, + ) + else: + dataset = ConcatDataset(lang_datasets) + lang_splits = [split] + for lang_id, lang_dataset in enumerate(lang_datasets): + split_name = split + "_" + languages[lang_id] + lang_splits.append(split_name) + self.datasets[split_name] = lang_dataset + + if split in self.args.valid_subset: + self.args.valid_subset = self.args.valid_subset.replace( + split, ",".join(lang_splits) + ) + + with data_utils.numpy_seed(self.args.seed + epoch): + shuffle = np.random.permutation(len(dataset)) + + self.datasets[split] = SortDataset( + dataset, + sort_order=[ + shuffle, + dataset.sizes, + ], + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_language_modeling.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_language_modeling.py new file mode 100644 index 00000000..8fd5e595 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_language_modeling.py @@ -0,0 +1,627 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +from dataclasses import dataclass, field +from typing import Optional + +import numpy as np +import torch +from omegaconf import II + +from fairseq import utils +from fairseq.data import ( + AppendTokenDataset, + ConcatDataset, + Dictionary, + IdDataset, + LMContextWindowDataset, + MonolingualDataset, + NestedDictionaryDataset, + NumelDataset, + PadDataset, + PrependTokenDataset, + ResamplingDataset, + SortDataset, + StripTokenDataset, + TokenBlockDataset, + TruncatedDictionary, + data_utils, +) +from fairseq.data.indexed_dataset import get_available_dataset_impl +from fairseq.data.shorten_dataset import maybe_shorten_dataset +from fairseq.dataclass import ChoiceEnum, FairseqDataclass +from fairseq.tasks import LegacyFairseqTask, register_task + +SAMPLE_BREAK_MODE_CHOICES = ChoiceEnum(["none", "complete", "complete_doc", "eos"]) +SHORTEN_METHOD_CHOICES = ChoiceEnum(["none", "truncate", "random_crop"]) +logger = logging.getLogger(__name__) + + +def lang_token(lang): + return f"<{lang}>" + + +@dataclass +class MultilingualLanguageModelingConfig(FairseqDataclass): + # TODO common var add to parent + data: Optional[str] = field( + default=None, metadata={"help": "path to data directory"} + ) + sample_break_mode: SAMPLE_BREAK_MODE_CHOICES = field( + default="none", + metadata={ + "help": 'If omitted or "none", fills each sample with tokens-per-sample ' + 'tokens. If set to "complete", splits samples only at the end ' + "of sentence, but may include multiple sentences per sample. " + '"complete_doc" is similar but respects doc boundaries. ' + 'If set to "eos", includes only one sentence per sample.' + }, + ) + tokens_per_sample: int = field( + default=1024, + metadata={"help": "max number of tokens per sample for LM dataset"}, + ) + output_dictionary_size: int = field( + default=-1, metadata={"help": "limit the size of output dictionary"} + ) + self_target: bool = field(default=False, metadata={"help": "include self target"}) + future_target: bool = field( + default=False, metadata={"help": "include future target"} + ) + past_target: bool = field(default=False, metadata={"help": "include past target"}) + add_bos_token: bool = field( + default=False, metadata={"help": "prepend lang id token "} + ) + max_source_positions: Optional[int] = field( + default=None, metadata={"help": "max number of tokens in the source sequence"} + ) + max_target_positions: Optional[int] = field( + default=None, metadata={"help": "max number of tokens in the target sequence"} + ) + pad_to_fixed_length: Optional[bool] = field( + default=False, metadata={"help": "pad to fixed length"} + ) + pad_to_fixed_bsz: Optional[bool] = field( + default=False, metadata={"help": "boolean to pad to fixed batch size"} + ) + + multilang_sampling_alpha: Optional[float] = field( + default=1.0, + metadata={ + "help": "smoothing alpha for sample rations across multiple datasets" + }, + ) + + shorten_method: SHORTEN_METHOD_CHOICES = field( + default="none", + metadata={ + "help": "if not none, shorten sequences that exceed --tokens-per-sample" + }, + ) + shorten_data_split_list: str = field( + default="", + metadata={ + "help": "comma-separated list of dataset splits to apply shortening to, " + 'e.g., "train,valid" (default: all dataset splits)' + }, + ) + + langs: str = field( + default="", + metadata={ + "help": "comma-separated list of languages (default: all directories in data path)" + }, + ) + baseline_model_langs: str = field( + default="", + metadata={ + "help": "comma-separated list of languages in the baseline model (default: none)" + }, + ) + # TODO: legacy parameter kept for compatibility + baseline_model: str = field( + default="", + metadata={"help": "path to the baseline model (default: none)"}, + ) + + lang_to_offline_shard_ratio: str = field( + default="", + metadata={ + "help": "absolute path of tsv file location to indicate lang to offline shard ratio.", + }, + ) + # TODO common vars below add to parent + seed: int = II("common.seed") + dataset_impl: Optional[ChoiceEnum(get_available_dataset_impl())] = II( + "dataset.dataset_impl" + ) + data_buffer_size: int = II("dataset.data_buffer_size") + tpu: bool = II("common.tpu") + batch_size: Optional[int] = II("dataset.batch_size") + batch_size_valid: Optional[int] = II("dataset.batch_size_valid") + train_subset: str = II("common.train_subset") + valid_subset: str = II("common.valid_subset") + + +@register_task( + "multilingual_language_modeling", dataclass=MultilingualLanguageModelingConfig +) +class MultilingualLanguageModelingTask(LegacyFairseqTask): + """ + Train a language model. + + Args: + dictionary (~fairseq.data.Dictionary): the dictionary for the input of + the language model + output_dictionary (~fairseq.data.Dictionary): the dictionary for the + output of the language model. In most cases it will be the same as + *dictionary*, but could possibly be a more limited version of the + dictionary (if ``--output-dictionary-size`` is used). + targets (List[str]): list of the target types that the language model + should predict. Can be one of "self", "future", and "past". + Defaults to "future". + + .. note:: + + The language modeling task is compatible with :mod:`fairseq-train`, + :mod:`fairseq-generate`, :mod:`fairseq-interactive` and + :mod:`fairseq-eval-lm`. + + The language modeling task provides the following additional command-line + arguments: + + .. argparse:: + :ref: fairseq.tasks.language_modeling_parser + :prog: + """ + + def __init__(self, args, dictionary, output_dictionary=None, targets=None): + super().__init__(args) + self.dictionary = dictionary + self.output_dictionary = output_dictionary or dictionary + + if targets is None: + targets = ["future"] + self.targets = targets + + @staticmethod + def _get_langs(args, epoch=1): + paths = utils.split_paths(args.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + + languages = sorted( + name + for name in os.listdir(data_path) + if os.path.isdir(os.path.join(data_path, name)) + ) + if args.langs: + keep_langs = set(args.langs.split(",")) + languages = [lang for lang in languages if lang in keep_langs] + assert len(languages) == len(keep_langs) + + return languages, data_path + + @classmethod + def setup_dictionary(cls, args, **kwargs): + dictionary = None + output_dictionary = None + if args.data: + paths = utils.split_paths(args.data) + assert len(paths) > 0 + dictionary = Dictionary.load(os.path.join(paths[0], "dict.txt")) + if args.add_bos_token: + languages, _ = cls._get_langs(args) + logger.info("----------------") + for lang in languages: + dictionary.add_symbol(lang_token(lang)) + logger.info(f"add language token: {lang_token(lang)}") + logger.info("----------------") + + logger.info("dictionary: {} types".format(len(dictionary))) + output_dictionary = dictionary + if args.output_dictionary_size >= 0: + output_dictionary = TruncatedDictionary( + dictionary, args.output_dictionary_size + ) + return (dictionary, output_dictionary) + + @classmethod + def setup_task(cls, args, **kwargs): + """Setup the task (e.g., load dictionaries). + + Args: + args (argparse.Namespace): parsed command-line arguments + """ + dictionary, output_dictionary = cls.setup_dictionary(args, **kwargs) + + # upgrade old checkpoints + if hasattr(args, "exclude_self_target"): + args.self_target = not args.exclude_self_target + + targets = [] + if getattr(args, "self_target", False): + targets.append("self") + if getattr(args, "future_target", False): + targets.append("future") + if getattr(args, "past_target", False): + targets.append("past") + if len(targets) == 0: + # standard language modeling + targets = ["future"] + + return cls(args, dictionary, output_dictionary, targets=targets) + + def build_model(self, args, from_checkpoint=False): + model = super().build_model(args, from_checkpoint) + for target in self.targets: + if target not in model.supported_targets: + raise ValueError( + f"Unsupported language modeling target: {target} not in {model.supported_targets}" + ) + + return model + + def _get_sample_prob(self, dataset_lens): + """ + Get smoothed sampling porbability by languages. This helps low resource + languages by upsampling them. + """ + prob = dataset_lens / dataset_lens.sum() + smoothed_prob = prob**self.args.multilang_sampling_alpha + smoothed_prob = smoothed_prob / smoothed_prob.sum() + return smoothed_prob + + def load_dataset(self, split: str, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + languages, data_path = MultilingualLanguageModelingTask._get_langs( + self.args, epoch + ) + lang_to_offline_shard_ratio = None + if self.args.lang_to_offline_shard_ratio != "": + lang_to_offline_shard_ratio = {} + assert os.path.exists( + self.args.lang_to_offline_shard_ratio + ), "provided offline shard ratio file doesn't exist: {0}".format( + self.args.lang_to_offline_shard_ratio + ) + with open(self.args.lang_to_offline_shard_ratio) as fin: + for line in fin: + lang, ratio = line.strip().split("\t") + ratio = float(ratio) + lang_to_offline_shard_ratio[lang] = ratio + + logger.info( + "Found offline sharded ratio: %s", + lang_to_offline_shard_ratio, + ) + + if split == self.args.train_subset: + logger.info( + "Training on {0} languages: {1}".format(len(languages), languages) + ) + else: + logger.info( + "Evaluating on {0} languages: {1}".format(len(languages), languages) + ) + + tokens_per_sample = self.args.tokens_per_sample - int(self.args.add_bos_token) + + fixed_pad_length = None + if self.args.pad_to_fixed_length: + fixed_pad_length = self.args.tokens_per_sample + + pad_to_bsz = None + if self.args.pad_to_fixed_bsz: + pad_to_bsz = ( + self.args.batch_size_valid if "valid" in split else self.args.batch_size + ) + + lang_datasets = [] + for lang_id, language in enumerate(languages): + split_path = os.path.join(data_path, language, split) + dataset = data_utils.load_indexed_dataset( + split_path, self.dictionary, self.args.dataset_impl, combine=combine + ) + # print('len(dataset) =', len(dataset)) + if dataset is None: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, split_path) + ) + + dataset = maybe_shorten_dataset( + dataset, + split, + self.args.shorten_data_split_list, + self.args.shorten_method, + tokens_per_sample, + self.args.seed, + ) + + dataset = TokenBlockDataset( + dataset, + dataset.sizes, + tokens_per_sample, + pad=self.dictionary.pad(), + eos=self.dictionary.eos(), + break_mode=self.args.sample_break_mode, + include_targets=True, + ) + + add_eos_for_other_targets = ( + self.args.sample_break_mode is not None + and self.args.sample_break_mode != "none" + ) + src_lang_idx, tgt_lang_idx = None, None + if self.args.add_bos_token: + src_lang_idx = self.dictionary.index(lang_token(language)) + tgt_lang_idx = self.output_dictionary.index(lang_token(language)) + + lang_datasets.append( + MonolingualDataset( + dataset=dataset, + sizes=dataset.sizes, + src_vocab=self.dictionary, + tgt_vocab=self.output_dictionary, + add_eos_for_other_targets=add_eos_for_other_targets, + shuffle=True, + targets=self.targets, + fixed_pad_length=fixed_pad_length, + pad_to_bsz=pad_to_bsz, + add_bos_token=self.args.add_bos_token, + src_lang_idx=src_lang_idx, + tgt_lang_idx=tgt_lang_idx, + ) + ) + + dataset_lengths = np.array( + [len(d) for d in lang_datasets], + dtype=float, + ) + logger.info( + "loaded total {} blocks for all languages".format( + dataset_lengths.sum(), + ) + ) + if split == self.args.train_subset: + dataset_lengths_ratio_multiplier = np.ones(len(dataset_lengths)) + if lang_to_offline_shard_ratio is not None: + dataset_lengths_ratio_multiplier = [] + for lang in languages: + assert ( + lang in lang_to_offline_shard_ratio + ), "Lang: {0} missing in offline shard ratio file: {1}".format( + lang, + self.args.lang_to_offline_shard_ratio, + ) + dataset_lengths_ratio_multiplier.append( + lang_to_offline_shard_ratio[lang] + ) + dataset_lengths_ratio_multiplier = np.array( + dataset_lengths_ratio_multiplier + ) + true_dataset_lengths = ( + dataset_lengths * dataset_lengths_ratio_multiplier + ) + else: + true_dataset_lengths = dataset_lengths + # For train subset, additionally up or down sample languages. + sample_probs = self._get_sample_prob(true_dataset_lengths) + + logger.info( + "Sample probability by language: %s", + { + lang: "{0:.4f}".format(sample_probs[id]) + for id, lang in enumerate(languages) + }, + ) + size_ratio = (sample_probs * true_dataset_lengths.sum()) / dataset_lengths + # TODO: add an option for shrinking all size ratios to below 1 + # if self.args.multilang_sampling_alpha != 1: + # size_ratio /= size_ratio.max() + + # Fix numeric errors in size ratio computation + # 0.999999999999999999 -> 1 + # 1.000000000000000002 -> 1 + for i in range(len(size_ratio)): + size_ratio[i] = round(size_ratio[i], 8) + + logger.info( + "Up/Down Sampling ratio by language: %s", + { + lang: "{0:.2f}".format(size_ratio[id]) + for id, lang in enumerate(languages) + }, + ) + logger.info( + "Actual dataset size by language: %s", + { + lang: "{0:.2f}".format(len(lang_datasets[id])) + for id, lang in enumerate(languages) + }, + ) + resampled_lang_datasets = [ + ResamplingDataset( + lang_datasets[i], + size_ratio=size_ratio[i], + seed=self.args.seed, + epoch=epoch, + replace=size_ratio[i] > 1.0, + ) + for i, d in enumerate(lang_datasets) + ] + logger.info( + "Resampled dataset size by language: %s", + { + lang: "{0:.2f}".format(len(resampled_lang_datasets[id])) + for id, lang in enumerate(languages) + }, + ) + dataset = ConcatDataset(resampled_lang_datasets) + else: + dataset = ConcatDataset(lang_datasets) + lang_splits = [split] + for lang_id, lang_dataset in enumerate(lang_datasets): + split_name = split + "_" + languages[lang_id] + lang_splits.append(split_name) + self.datasets[split_name] = lang_dataset + + # [TODO]: This is hacky for now to print validation ppl for each + # language individually. Maybe need task API changes to allow it + # in more generic ways. + if split in self.args.valid_subset: + self.args.valid_subset = self.args.valid_subset.replace( + split, ",".join(lang_splits) + ) + + with data_utils.numpy_seed(self.args.seed + epoch): + shuffle = np.random.permutation(len(dataset)) + + self.datasets[split] = SortDataset( + dataset, + sort_order=[ + shuffle, + dataset.sizes, + ], + ) + + def build_dataset_for_inference( + self, src_tokens, src_lengths, language="en_XX", **kwargs + ): + """ + Generate batches for inference. We prepend an eos token to src_tokens + (or bos if `--add-bos-token` is set) and we append a to target. + This is convenient both for generation with a prefix and LM scoring. + """ + dataset = StripTokenDataset( + TokenBlockDataset( + src_tokens, + src_lengths, + block_size=None, # ignored for "eos" break mode + pad=self.source_dictionary.pad(), + eos=self.source_dictionary.eos(), + break_mode="eos", + ), + # remove eos from (end of) target sequence + self.source_dictionary.eos(), + ) + + src_lang_idx = self.dictionary.index(lang_token(language)) + src_dataset = PrependTokenDataset( + dataset, + token=( + (src_lang_idx or self.source_dictionary.bos()) + if getattr(self.args, "add_bos_token", False) + else self.source_dictionary.eos() + ), + ) + + max_seq_len = max(src_lengths) + 1 + tgt_dataset = AppendTokenDataset(dataset, token=self.source_dictionary.pad()) + return NestedDictionaryDataset( + { + "id": IdDataset(), + "net_input": { + "src_tokens": PadDataset( + src_dataset, + pad_idx=self.source_dictionary.pad(), + left_pad=False, + pad_length=max_seq_len, + ), + "src_lengths": NumelDataset(src_dataset, reduce=False), + }, + "target": PadDataset( + tgt_dataset, + pad_idx=self.source_dictionary.pad(), + left_pad=False, + pad_length=max_seq_len, + ), + }, + sizes=[np.array(src_lengths)], + ) + + @torch.no_grad() + def inference_step( + self, + generator, + models, + sample, + language="en_XX", + prefix_tokens=None, + constraints=None, + ): + # Generation will always be conditioned on bos_token + if getattr(self.args, "add_bos_token", False): + src_lang_idx = self.dictionary.index(lang_token(language)) + bos_token = src_lang_idx or self.source_dictionary.bos() + else: + bos_token = self.source_dictionary.eos() + + if constraints is not None: + raise NotImplementedError( + "Constrained decoding with the language_modeling task is not supported" + ) + + # SequenceGenerator doesn't use src_tokens directly, we need to + # pass the `prefix_tokens` argument instead + if prefix_tokens is None and sample["net_input"]["src_tokens"].nelement(): + prefix_tokens = sample["net_input"]["src_tokens"] + if prefix_tokens[:, 0].eq(bos_token).all(): + prefix_tokens = prefix_tokens[:, 1:] + + return generator.generate( + models, sample, prefix_tokens=prefix_tokens, bos_token=bos_token + ) + + def eval_lm_dataloader( + self, + dataset, + max_tokens: Optional[int] = 36000, + batch_size: Optional[int] = None, + max_positions: Optional[int] = None, + num_shards: int = 1, + shard_id: int = 0, + num_workers: int = 1, + data_buffer_size: int = 10, + # ensures that every evaluated token has access to a context of at least + # this size, if possible + context_window: int = 0, + ): + if context_window > 0: + dataset = LMContextWindowDataset( + dataset=dataset, + tokens_per_sample=self.args.tokens_per_sample, + context_window=context_window, + pad_idx=self.source_dictionary.pad(), + ) + return self.get_batch_iterator( + dataset=dataset, + max_tokens=max_tokens, + max_sentences=batch_size, + max_positions=max_positions, + ignore_invalid_inputs=True, + num_shards=num_shards, + shard_id=shard_id, + num_workers=num_workers, + data_buffer_size=data_buffer_size, + ) + + @property + def source_dictionary(self): + """Return the :class:`~fairseq.data.Dictionary` for the language + model.""" + return self.dictionary + + @property + def target_dictionary(self): + """Return the :class:`~fairseq.data.Dictionary` for the language + model.""" + return self.output_dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_masked_lm.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_masked_lm.py new file mode 100644 index 00000000..156d085a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_masked_lm.py @@ -0,0 +1,338 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os + +import numpy as np +import torch + +from fairseq import utils +from fairseq.data import ( + ConcatDataset, + Dictionary, + IdDataset, + MaskTokensDataset, + NestedDictionaryDataset, + NumelDataset, + NumSamplesDataset, + PadDataset, + PrependTokenDataset, + RawLabelDataset, + ResamplingDataset, + SortDataset, + TokenBlockDataset, + data_utils, + encoders, +) +from fairseq.tasks import LegacyFairseqTask, register_task + +logger = logging.getLogger(__name__) + + +@register_task("multilingual_masked_lm") +class MultiLingualMaskedLMTask(LegacyFairseqTask): + """Task for training masked language models (e.g., BERT, RoBERTa).""" + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + parser.add_argument( + "data", + help="colon separated path to data directories list, \ + will be iterated upon during epochs in round-robin manner", + ) + parser.add_argument( + "--sample-break-mode", + default="complete", + choices=["none", "complete", "complete_doc", "eos"], + help='If omitted or "none", fills each sample with tokens-per-sample ' + 'tokens. If set to "complete", splits samples only at the end ' + "of sentence, but may include multiple sentences per sample. " + '"complete_doc" is similar but respects doc boundaries. ' + 'If set to "eos", includes only one sentence per sample.', + ) + parser.add_argument( + "--tokens-per-sample", + default=512, + type=int, + help="max number of total tokens over all segments " + "per sample for BERT dataset", + ) + parser.add_argument( + "--mask-prob", + default=0.15, + type=float, + help="probability of replacing a token with mask", + ) + parser.add_argument( + "--leave-unmasked-prob", + default=0.1, + type=float, + help="probability that a masked token is unmasked", + ) + parser.add_argument( + "--random-token-prob", + default=0.1, + type=float, + help="probability of replacing a token with a random token", + ) + parser.add_argument( + "--freq-weighted-replacement", + action="store_true", + help="sample random replacement words based on word frequencies", + ) + parser.add_argument( + "--mask-whole-words", + default=False, + action="store_true", + help="mask whole words; you may also want to set --bpe", + ) + parser.add_argument( + "--multilang-sampling-alpha", + type=float, + default=1.0, + help="smoothing alpha for sample rations across multiple datasets", + ) + + def __init__(self, args, dictionary): + super().__init__(args) + self.dictionary = dictionary + self.seed = args.seed + + # add mask token + self.mask_idx = dictionary.add_symbol("") + + @classmethod + def setup_task(cls, args, **kwargs): + paths = utils.split_paths(args.data) + assert len(paths) > 0 + dictionary = Dictionary.load(os.path.join(paths[0], "dict.txt")) + logger.info("dictionary: {} types".format(len(dictionary))) + return cls(args, dictionary) + + def _get_whole_word_mask(self): + # create masked input and targets + if self.args.mask_whole_words: + bpe = encoders.build_bpe(self.args) + if bpe is not None: + + def is_beginning_of_word(i): + if i < self.source_dictionary.nspecial: + # special elements are always considered beginnings + return True + tok = self.source_dictionary[i] + if tok.startswith("madeupword"): + return True + try: + return bpe.is_beginning_of_word(tok) + except ValueError: + return True + + mask_whole_words = torch.ByteTensor( + list(map(is_beginning_of_word, range(len(self.source_dictionary)))) + ) + else: + mask_whole_words = None + return mask_whole_words + + def _get_sample_prob(self, dataset_lens): + """ + Get smoothed sampling porbability by languages. This helps low resource + languages by upsampling them. + """ + prob = dataset_lens / dataset_lens.sum() + smoothed_prob = prob**self.args.multilang_sampling_alpha + smoothed_prob = smoothed_prob / smoothed_prob.sum() + return smoothed_prob + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + paths = utils.split_paths(self.args.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + + languages = sorted( + name + for name in os.listdir(data_path) + if os.path.isdir(os.path.join(data_path, name)) + ) + + logger.info("Training on {0} languages: {1}".format(len(languages), languages)) + logger.info( + "Language to id mapping: ", {lang: id for id, lang in enumerate(languages)} + ) + + mask_whole_words = self._get_whole_word_mask() + lang_datasets = [] + for lang_id, language in enumerate(languages): + split_path = os.path.join(data_path, language, split) + + dataset = data_utils.load_indexed_dataset( + split_path, + self.source_dictionary, + self.args.dataset_impl, + combine=combine, + ) + if dataset is None: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, split_path) + ) + + # create continuous blocks of tokens + dataset = TokenBlockDataset( + dataset, + dataset.sizes, + self.args.tokens_per_sample - 1, # one less for + pad=self.source_dictionary.pad(), + eos=self.source_dictionary.eos(), + break_mode=self.args.sample_break_mode, + ) + logger.info("loaded {} blocks from: {}".format(len(dataset), split_path)) + + # prepend beginning-of-sentence token (, equiv. to [CLS] in BERT) + dataset = PrependTokenDataset(dataset, self.source_dictionary.bos()) + + src_dataset, tgt_dataset = MaskTokensDataset.apply_mask( + dataset, + self.source_dictionary, + pad_idx=self.source_dictionary.pad(), + mask_idx=self.mask_idx, + seed=self.args.seed, + mask_prob=self.args.mask_prob, + leave_unmasked_prob=self.args.leave_unmasked_prob, + random_token_prob=self.args.random_token_prob, + freq_weighted_replacement=self.args.freq_weighted_replacement, + mask_whole_words=mask_whole_words, + ) + + lang_dataset = NestedDictionaryDataset( + { + "net_input": { + "src_tokens": PadDataset( + src_dataset, + pad_idx=self.source_dictionary.pad(), + left_pad=False, + ), + "src_lengths": NumelDataset(src_dataset, reduce=False), + }, + "target": PadDataset( + tgt_dataset, + pad_idx=self.source_dictionary.pad(), + left_pad=False, + ), + "nsentences": NumSamplesDataset(), + "ntokens": NumelDataset(src_dataset, reduce=True), + "lang_id": RawLabelDataset([lang_id] * src_dataset.sizes.shape[0]), + }, + sizes=[src_dataset.sizes], + ) + lang_datasets.append(lang_dataset) + + dataset_lengths = np.array( + [len(d) for d in lang_datasets], + dtype=float, + ) + logger.info( + "loaded total {} blocks for all languages".format( + dataset_lengths.sum(), + ) + ) + if split == self.args.train_subset: + # For train subset, additionally up or down sample languages. + sample_probs = self._get_sample_prob(dataset_lengths) + logger.info( + "Sample probability by language: ", + { + lang: "{0:.4f}".format(sample_probs[id]) + for id, lang in enumerate(languages) + }, + ) + size_ratio = (sample_probs * dataset_lengths.sum()) / dataset_lengths + logger.info( + "Up/Down Sampling ratio by language: ", + { + lang: "{0:.2f}".format(size_ratio[id]) + for id, lang in enumerate(languages) + }, + ) + + resampled_lang_datasets = [ + ResamplingDataset( + lang_datasets[i], + size_ratio=size_ratio[i], + seed=self.args.seed, + epoch=epoch, + replace=size_ratio[i] >= 1.0, + ) + for i, d in enumerate(lang_datasets) + ] + dataset = ConcatDataset(resampled_lang_datasets) + else: + dataset = ConcatDataset(lang_datasets) + lang_splits = [split] + for lang_id, lang_dataset in enumerate(lang_datasets): + split_name = split + "_" + languages[lang_id] + lang_splits.append(split_name) + self.datasets[split_name] = lang_dataset + + # [TODO]: This is hacky for now to print validation ppl for each + # language individually. Maybe need task API changes to allow it + # in more generic ways. + if split in self.args.valid_subset: + self.args.valid_subset = self.args.valid_subset.replace( + split, ",".join(lang_splits) + ) + + with data_utils.numpy_seed(self.args.seed + epoch): + shuffle = np.random.permutation(len(dataset)) + + self.datasets[split] = SortDataset( + dataset, + sort_order=[ + shuffle, + dataset.sizes, + ], + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, sort=True): + src_dataset = PadDataset( + TokenBlockDataset( + src_tokens, + src_lengths, + self.args.tokens_per_sample - 1, # one less for + pad=self.source_dictionary.pad(), + eos=self.source_dictionary.eos(), + break_mode="eos", + ), + pad_idx=self.source_dictionary.pad(), + left_pad=False, + ) + src_dataset = PrependTokenDataset(src_dataset, self.source_dictionary.bos()) + src_dataset = NestedDictionaryDataset( + { + "id": IdDataset(), + "net_input": { + "src_tokens": src_dataset, + "src_lengths": NumelDataset(src_dataset, reduce=False), + }, + }, + sizes=src_lengths, + ) + if sort: + src_dataset = SortDataset(src_dataset, sort_order=[src_lengths]) + return src_dataset + + @property + def source_dictionary(self): + return self.dictionary + + @property + def target_dictionary(self): + return self.dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_translation.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_translation.py new file mode 100644 index 00000000..e692b666 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/multilingual_translation.py @@ -0,0 +1,462 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import contextlib +import logging +import os +from collections import OrderedDict +from argparse import ArgumentError + +import torch +from fairseq import metrics, options, utils +from fairseq.data import ( + Dictionary, + LanguagePairDataset, + RoundRobinZipDatasets, + TransformEosLangPairDataset, +) +from fairseq.models import FairseqMultiModel +from fairseq.tasks.translation import load_langpair_dataset + +from . import LegacyFairseqTask, register_task + + +logger = logging.getLogger(__name__) + + +def _lang_token(lang: str): + return "__{}__".format(lang) + + +def _lang_token_index(dic: Dictionary, lang: str): + """Return language token index.""" + idx = dic.index(_lang_token(lang)) + assert idx != dic.unk_index, "cannot find language token for lang {}".format(lang) + return idx + + +@register_task("multilingual_translation") +class MultilingualTranslationTask(LegacyFairseqTask): + """A task for training multiple translation models simultaneously. + + We iterate round-robin over batches from multiple language pairs, ordered + according to the `--lang-pairs` argument. + + The training loop is roughly: + + for i in range(len(epoch)): + for lang_pair in args.lang_pairs: + batch = next_batch_for_lang_pair(lang_pair) + loss = criterion(model_for_lang_pair(lang_pair), batch) + loss.backward() + optimizer.step() + + In practice, `next_batch_for_lang_pair` is abstracted in a FairseqDataset + (e.g., `RoundRobinZipDatasets`) and `model_for_lang_pair` is a model that + implements the `FairseqMultiModel` interface. + + During inference it is required to specify a single `--source-lang` and + `--target-lang`, which indicates the inference langauge direction. + `--lang-pairs`, `--encoder-langtok`, `--decoder-langtok` have to be set to + the same value as training. + """ + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + # fmt: off + parser.add_argument('data', metavar='DIR', help='path to data directory') + parser.add_argument('--lang-pairs', default=None, metavar='PAIRS', + help='comma-separated list of language pairs (in training order): en-de,en-fr,de-fr') + parser.add_argument('-s', '--source-lang', default=None, metavar='SRC', + help='source language (only needed for inference)') + parser.add_argument('-t', '--target-lang', default=None, metavar='TARGET', + help='target language (only needed for inference)') + parser.add_argument('--left-pad-source', default='True', type=str, metavar='BOOL', + help='pad the source on the left (default: True)') + parser.add_argument('--left-pad-target', default='False', type=str, metavar='BOOL', + help='pad the target on the left (default: False)') + try: + parser.add_argument('--max-source-positions', default=1024, type=int, metavar='N', + help='max number of tokens in the source sequence') + parser.add_argument('--max-target-positions', default=1024, type=int, metavar='N', + help='max number of tokens in the target sequence') + except ArgumentError: + # this might have already been defined. Once we transition this to hydra it should be fine to add it here. + pass + parser.add_argument('--upsample-primary', default=1, type=int, + help='amount to upsample primary dataset') + parser.add_argument('--encoder-langtok', default=None, type=str, choices=['src', 'tgt'], + metavar='SRCTGT', + help='replace beginning-of-sentence in source sentence with source or target ' + 'language token. (src/tgt)') + parser.add_argument('--decoder-langtok', action='store_true', + help='replace beginning-of-sentence in target sentence with target language token') + # fmt: on + + def __init__(self, args, dicts, training): + super().__init__(args) + self.dicts = dicts + self.training = training + if training: + self.lang_pairs = args.lang_pairs + else: + self.lang_pairs = ["{}-{}".format(args.source_lang, args.target_lang)] + # eval_lang_pairs for multilingual translation is usually all of the + # lang_pairs. However for other multitask settings or when we want to + # optimize for certain languages we want to use a different subset. Thus + # the eval_lang_pairs class variable is provided for classes that extend + # this class. + self.eval_lang_pairs = self.lang_pairs + # model_lang_pairs will be used to build encoder-decoder model pairs in + # models.build_model(). This allows multitask type of sub-class can + # build models other than the input lang_pairs + self.model_lang_pairs = self.lang_pairs + self.langs = list(dicts.keys()) + + @classmethod + def setup_task(cls, args, **kwargs): + dicts, training = cls.prepare(args, **kwargs) + return cls(args, dicts, training) + + @classmethod + def update_args(cls, args): + args.left_pad_source = utils.eval_bool(args.left_pad_source) + args.left_pad_target = utils.eval_bool(args.left_pad_target) + + if args.lang_pairs is None: + raise ValueError( + "--lang-pairs is required. List all the language pairs in the training objective." + ) + if isinstance(args.lang_pairs, str): + args.lang_pairs = args.lang_pairs.split(",") + + @classmethod + def prepare(cls, args, **kargs): + cls.update_args(args) + sorted_langs = sorted( + list({x for lang_pair in args.lang_pairs for x in lang_pair.split("-")}) + ) + if args.source_lang is not None or args.target_lang is not None: + training = False + else: + training = True + + # load dictionaries + dicts = OrderedDict() + for lang in sorted_langs: + paths = utils.split_paths(args.data) + assert len(paths) > 0 + dicts[lang] = cls.load_dictionary( + os.path.join(paths[0], "dict.{}.txt".format(lang)) + ) + if len(dicts) > 0: + assert dicts[lang].pad() == dicts[sorted_langs[0]].pad() + assert dicts[lang].eos() == dicts[sorted_langs[0]].eos() + assert dicts[lang].unk() == dicts[sorted_langs[0]].unk() + if args.encoder_langtok is not None or args.decoder_langtok: + for lang_to_add in sorted_langs: + dicts[lang].add_symbol(_lang_token(lang_to_add)) + logger.info("[{}] dictionary: {} types".format(lang, len(dicts[lang]))) + return dicts, training + + def get_encoder_langtok(self, src_lang, tgt_lang): + if self.args.encoder_langtok is None: + return self.dicts[src_lang].eos() + if self.args.encoder_langtok == "src": + return _lang_token_index(self.dicts[src_lang], src_lang) + else: + return _lang_token_index(self.dicts[src_lang], tgt_lang) + + def get_decoder_langtok(self, tgt_lang): + if not self.args.decoder_langtok: + return self.dicts[tgt_lang].eos() + return _lang_token_index(self.dicts[tgt_lang], tgt_lang) + + def alter_dataset_langtok( + self, + lang_pair_dataset, + src_eos=None, + src_lang=None, + tgt_eos=None, + tgt_lang=None, + ): + if self.args.encoder_langtok is None and not self.args.decoder_langtok: + return lang_pair_dataset + + new_src_eos = None + if ( + self.args.encoder_langtok is not None + and src_eos is not None + and src_lang is not None + and tgt_lang is not None + ): + new_src_eos = self.get_encoder_langtok(src_lang, tgt_lang) + else: + src_eos = None + + new_tgt_bos = None + if self.args.decoder_langtok and tgt_eos is not None and tgt_lang is not None: + new_tgt_bos = self.get_decoder_langtok(tgt_lang) + else: + tgt_eos = None + + return TransformEosLangPairDataset( + lang_pair_dataset, + src_eos=src_eos, + new_src_eos=new_src_eos, + tgt_bos=tgt_eos, + new_tgt_bos=new_tgt_bos, + ) + + def load_dataset(self, split, epoch=1, **kwargs): + """Load a dataset split.""" + paths = utils.split_paths(self.args.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + + def language_pair_dataset(lang_pair): + src, tgt = lang_pair.split("-") + langpair_dataset = load_langpair_dataset( + data_path, + split, + src, + self.dicts[src], + tgt, + self.dicts[tgt], + combine=True, + dataset_impl=self.args.dataset_impl, + upsample_primary=self.args.upsample_primary, + left_pad_source=self.args.left_pad_source, + left_pad_target=self.args.left_pad_target, + max_source_positions=self.args.max_source_positions, + max_target_positions=self.args.max_target_positions, + ) + return self.alter_dataset_langtok( + langpair_dataset, + src_eos=self.dicts[src].eos(), + src_lang=src, + tgt_eos=self.dicts[tgt].eos(), + tgt_lang=tgt, + ) + + self.datasets[split] = RoundRobinZipDatasets( + OrderedDict( + [ + (lang_pair, language_pair_dataset(lang_pair)) + for lang_pair in self.lang_pairs + ] + ), + eval_key=None + if self.training + else "%s-%s" % (self.args.source_lang, self.args.target_lang), + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, constraints=None): + if constraints is not None: + raise NotImplementedError( + "Constrained decoding with the multilingual_translation task is not supported" + ) + + lang_pair = "%s-%s" % (self.args.source_lang, self.args.target_lang) + return RoundRobinZipDatasets( + OrderedDict( + [ + ( + lang_pair, + self.alter_dataset_langtok( + LanguagePairDataset( + src_tokens, src_lengths, self.source_dictionary + ), + src_eos=self.source_dictionary.eos(), + src_lang=self.args.source_lang, + tgt_eos=self.target_dictionary.eos(), + tgt_lang=self.args.target_lang, + ), + ) + ] + ), + eval_key=lang_pair, + ) + + def build_model(self, args, from_checkpoint=False): + def check_args(): + messages = [] + if ( + len(set(self.args.lang_pairs).symmetric_difference(args.lang_pairs)) + != 0 + ): + messages.append( + "--lang-pairs should include all the language pairs {}.".format( + args.lang_pairs + ) + ) + if self.args.encoder_langtok != args.encoder_langtok: + messages.append( + "--encoder-langtok should be {}.".format(args.encoder_langtok) + ) + if self.args.decoder_langtok != args.decoder_langtok: + messages.append( + "--decoder-langtok should {} be set.".format( + "" if args.decoder_langtok else "not" + ) + ) + + if len(messages) > 0: + raise ValueError(" ".join(messages)) + + # Update args -> the fact that the constructor here + # changes the args object doesn't mean you get the same one here + self.update_args(args) + + # Check if task args are consistant with model args + check_args() + + from fairseq import models + + model = models.build_model(args, self, from_checkpoint) + if not isinstance(model, FairseqMultiModel): + raise ValueError( + "MultilingualTranslationTask requires a FairseqMultiModel architecture" + ) + return model + + def _per_lang_pair_train_loss( + self, lang_pair, model, update_num, criterion, sample, optimizer, ignore_grad + ): + loss, sample_size, logging_output = criterion( + model.models[lang_pair], sample[lang_pair] + ) + if ignore_grad: + loss *= 0 + optimizer.backward(loss) + return loss, sample_size, logging_output + + def train_step( + self, sample, model, criterion, optimizer, update_num, ignore_grad=False + ): + model.train() + from collections import defaultdict + + agg_loss, agg_sample_size, agg_logging_output = 0.0, 0.0, defaultdict(float) + curr_lang_pairs = [ + lang_pair + for lang_pair in self.model_lang_pairs + if sample[lang_pair] is not None and len(sample[lang_pair]) != 0 + ] + + for idx, lang_pair in enumerate(curr_lang_pairs): + + def maybe_no_sync(): + if ( + self.args.distributed_world_size > 1 + and hasattr(model, "no_sync") + and idx < len(curr_lang_pairs) - 1 + ): + return model.no_sync() + else: + return contextlib.ExitStack() # dummy contextmanager + + with maybe_no_sync(): + loss, sample_size, logging_output = self._per_lang_pair_train_loss( + lang_pair, + model, + update_num, + criterion, + sample, + optimizer, + ignore_grad, + ) + agg_loss += loss.detach().item() + # TODO make summing of the sample sizes configurable + agg_sample_size += sample_size + for k in logging_output: + agg_logging_output[k] += logging_output[k] + agg_logging_output[f"{lang_pair}:{k}"] += logging_output[k] + return agg_loss, agg_sample_size, agg_logging_output + + def _per_lang_pair_valid_loss(self, lang_pair, model, criterion, sample): + return criterion(model.models[lang_pair], sample[lang_pair]) + + def valid_step(self, sample, model, criterion): + model.eval() + with torch.no_grad(): + from collections import defaultdict + + agg_loss, agg_sample_size, agg_logging_output = 0.0, 0.0, defaultdict(float) + for lang_pair in self.eval_lang_pairs: + if ( + lang_pair not in sample + or sample[lang_pair] is None + or len(sample[lang_pair]) == 0 + ): + continue + loss, sample_size, logging_output = self._per_lang_pair_valid_loss( + lang_pair, model, criterion, sample + ) + agg_loss += loss.data.item() + # TODO make summing of the sample sizes configurable + agg_sample_size += sample_size + for k in logging_output: + agg_logging_output[k] += logging_output[k] + agg_logging_output[f"{lang_pair}:{k}"] += logging_output[k] + return agg_loss, agg_sample_size, agg_logging_output + + def inference_step( + self, generator, models, sample, prefix_tokens=None, constraints=None + ): + with torch.no_grad(): + if self.args.decoder_langtok: + bos_token = _lang_token_index( + self.target_dictionary, self.args.target_lang + ) + else: + bos_token = self.target_dictionary.eos() + return generator.generate( + models, + sample, + prefix_tokens=prefix_tokens, + constraints=constraints, + bos_token=bos_token, + ) + + def reduce_metrics(self, logging_outputs, criterion): + with metrics.aggregate(): + # pass 'sample_size', 'nsentences', 'ntokens' stats to fairseq_task + super().reduce_metrics(logging_outputs, criterion) + for k in ["sample_size", "nsentences", "ntokens"]: + metrics.log_scalar(k, sum(l[k] for l in logging_outputs)) + + @property + def source_dictionary(self): + if self.training: + return next(iter(self.dicts.values())) + else: + return self.dicts[self.args.source_lang] + + @property + def target_dictionary(self): + if self.training: + return next(iter(self.dicts.values())) + else: + return self.dicts[self.args.target_lang] + + def max_positions(self): + """Return the max sentence length allowed by the task.""" + if len(self.datasets.values()) == 0: + return { + "%s-%s" + % (self.args.source_lang, self.args.target_lang): ( + self.args.max_source_positions, + self.args.max_target_positions, + ) + } + return OrderedDict( + [ + (key, (self.args.max_source_positions, self.args.max_target_positions)) + for split in self.datasets.keys() + for key in self.datasets[split].datasets.keys() + ] + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/online_backtranslation.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/online_backtranslation.py new file mode 100644 index 00000000..52ce58ce --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/online_backtranslation.py @@ -0,0 +1,682 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import contextlib +import json +import logging +import math +import os +from argparse import Namespace +from collections import OrderedDict, defaultdict +from pathlib import Path +from typing import Dict, Sequence, Tuple +from argparse import ArgumentError + +import numpy as np +import torch +import torch.nn as nn +import torch.nn.functional as F + +import fairseq +from fairseq import metrics, options, utils +from fairseq.data import ( + FairseqDataset, + LanguagePairDataset, + NoisingDataset, + PrependTokenDataset, + RoundRobinZipDatasets, + TransformEosLangPairDataset, + data_utils, + encoders, +) +from fairseq.sequence_generator import SequenceGenerator +from fairseq.tasks import register_task +from fairseq.tasks.translation import TranslationTask, load_langpair_dataset + +logger = logging.getLogger(__name__) + + +class PiecewiseLinearFn: + """Piecewise linear function. Can be configured with a string.""" + + def __init__(self, pieces: Sequence[Tuple[int, float]]): + assert pieces == sorted( + pieces + ), f"PiecewiseLinearFn configuration should be sorted, received: {pieces}" + + self.pieces = pieces + + def __call__(self, x: int) -> float: + for i, (x_a, y_a) in enumerate(self.pieces[:-1]): + x_b, y_b = self.pieces[i + 1] + if x_a <= x <= x_b: + return y_a + (x - x_a) * (y_b - y_a) / (x_b - x_a) + + return self.pieces[-1][1] + + @staticmethod + def from_string(configuration: str) -> "PiecewiseLinearFn": + """ + Parse the configuration of lambda coefficient (for scheduling). + x = "3" # lambda will be a constant equal to x + x = "0:1,1000:0" # lambda will start from 1 and linearly decrease + # to 0 during the first 1000 iterations + x = "0:0,1000:0,2000:1" # lambda will be equal to 0 for the first 1000 + # iterations, then will linearly increase to 1 until iteration 2000 + """ + if isinstance(configuration, float): + return PiecewiseLinearFn([(0, configuration)]) + + try: + parts = configuration.split(",") + if len(parts) == 1: + v = float(configuration) + return PiecewiseLinearFn([(0, v)]) + + split = [s.split(":") for s in parts] + pieces = [(int(t), float(v)) for t, v in split] + return PiecewiseLinearFn(pieces) + except Exception: + raise ValueError( + f"Invalid PiecewiseLinearFn configuration: {configuration!r}" + ) + + @staticmethod + def one() -> "PiecewiseLinearFn": + return PiecewiseLinearFn([(0, 1.0)]) + + +@register_task("online_backtranslation") +class OnlineBackTranslationTask(TranslationTask): + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + # fmt: off + # Generic translation args + parser.add_argument('data', help='colon separated path to data directories list, \ + will be iterated upon during epochs in round-robin manner; \ + however, valid and test data are always in the first directory to \ + avoid the need for repeating them in all directories') + parser.add_argument('--mono-langs', metavar='MONO_LANGS', + help='monolingual languages for training') + parser.add_argument('--valid-lang-pairs', default=None, metavar='VALID_LANG_PAIRS', + help='language pairs for validation') + parser.add_argument('--load-alignments', action='store_true', + help='load the binarized alignments') + parser.add_argument('--left-pad-source', default='False', type=str, metavar='BOOL', + help='pad the source on the left') + parser.add_argument('--left-pad-target', default='False', type=str, metavar='BOOL', + help='pad the target on the left') + parser.add_argument('--upsample-primary', default=1, type=int, + help='amount to upsample primary dataset') + try: + parser.add_argument('--max-source-positions', default=1024, type=int, metavar='N', + help='max number of tokens in the source sequence') + parser.add_argument('--max-target-positions', default=1024, type=int, metavar='N', + help='max number of tokens in the target sequence') + except ArgumentError: + # this might have already been defined. Once we transition this to hydra it should be fine to add it here. + pass + parser.add_argument('--truncate-source', action='store_true', default=False, + help='truncate source to max-source-positions') + parser.add_argument('--num-batch-buckets', default=0, type=int, metavar='N', + help='if >0, then bucket source and target lengths into N ' + 'buckets and pad accordingly; this is useful on TPUs ' + 'to minimize the number of compilations') + + # Denoising args + parser.add_argument('--max-word-shuffle-distance', default=3.0, type=float, metavar='N', + help='maximum word shuffle distance for denoising autoencoding data generation') + parser.add_argument('--word-dropout-prob', default=0.1, type=float, metavar='N', + help='word dropout probability for denoising autoencoding data generation') + parser.add_argument('--word-blanking-prob', default=0.2, type=float, metavar='N', + help='word blanking probability for denoising autoencoding data generation') + + # Backtranslation args + parser.add_argument('--lambda-bt', default="1.0", type=str, metavar='N', + help='back-translation weight') + parser.add_argument('--lambda-dae', default="1.0", type=str, metavar='N', + help='denoising auto-encoder weight') + + # Evaluation args + parser.add_argument('--generate-one-by-one', action='store_true', + help='generate one sentence at a time for backtranslation') + + parser.add_argument('--eval-bleu', action='store_true', + help='evaluation with BLEU scores') + parser.add_argument('--eval-bleu-detok', type=str, default="space", + help='detokenize before computing BLEU (e.g., "moses"); ' + 'required if using --eval-bleu; use "space" to ' + 'disable detokenization; see fairseq.data.encoders ' + 'for other options') + parser.add_argument('--eval-bleu-detok-args', type=str, metavar='JSON', + help='args for building the tokenizer, if needed') + parser.add_argument('--eval-tokenized-bleu', action='store_true', default=False, + help='compute tokenized BLEU instead of sacrebleu') + parser.add_argument('--eval-bleu-remove-bpe', nargs='?', const='@@ ', default=None, + help='remove BPE before computing BLEU') + parser.add_argument('--eval-bleu-args', type=str, metavar='JSON', + help='generation args for BLUE scoring, ' + 'e.g., \'{"beam": 4, "lenpen": 0.6}\'') + parser.add_argument('--eval-bleu-print-samples', action='store_true', + help='print sample generations during validation') + # fmt: on + + def __init__(self, args, common_dict, mono_langs, valid_lang_pairs): + super().__init__(args, common_dict, common_dict) + self.common_dict = common_dict + self.mono_langs = mono_langs + self.valid_lang_pairs = valid_lang_pairs + + self.SHOW_SAMPLES_INTERVAL = 1000 + # Start by showing samples + self._show_samples_ctr = self.SHOW_SAMPLES_INTERVAL + self.SHOW_SAMPLES_NUMBER = 5 + self.lambda_bt = PiecewiseLinearFn.from_string(args.lambda_bt) + self.lambda_dae = PiecewiseLinearFn.from_string(args.lambda_dae) + + self.args = args + self.data = utils.split_paths(self.args.data) + if len(self.data) == 1: + shards = list(Path(self.data[0]).glob("shard*")) + if len(shards) > 0: + # keep this as strings, since it can also be a manifold path + old_data = self.data + self.data = [str(shard) for shard in shards] + logging.warning(f"Expanded data directory {old_data} to {self.data}") + + @classmethod + def setup_task(cls, args, **kwargs): + """Setup the task (e.g., load dictionaries). + + Args: + args (argparse.Namespace): parsed command-line arguments + """ + args.left_pad_source = options.eval_bool(args.left_pad_source) + args.left_pad_target = options.eval_bool(args.left_pad_target) + + paths = utils.split_paths(args.data) + assert len(paths) > 0 + assert args.mono_langs is not None + + mono_langs = args.mono_langs.split(",") + valid_lang_pairs = args.valid_lang_pairs.split(",") + + # load dictionary + dict_path = os.path.join(paths[0], "dict.txt") + common_dict = cls.load_dictionary(dict_path) + + return cls(args, common_dict, mono_langs, valid_lang_pairs) + + def load_dataset(self, split, epoch=1, combine=False, **kwargs) -> FairseqDataset: + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + if split == "train": + data_path = self.data[(epoch - 1) % len(self.data)] + dataset = self.load_train_dataset(data_path) + else: + # valid/test should always be the same. + dataset = self.load_translation_dataset(split, self.data[0]) + + self.datasets[split] = dataset + return dataset + + def load_train_dataset(self, data_path: str) -> FairseqDataset: + """The training dataset is made of backtranslation dataset and denoising dataset.""" + data = [] + for lang in self.mono_langs: + train_path = os.path.join(data_path, lang, "train") + # TODO: could we do the BT using denoise sample ? + # this would half the data loading work + data.append((f"{lang}-BT", self.load_bt_dataset(train_path, lang))) + data.append( + (f"{lang}-DENOISE", self.load_denoise_dataset(train_path, lang)) + ) + + return RoundRobinZipDatasets(OrderedDict(data)) + + def _langpair_dataset( + self, src: FairseqDataset, tgt: FairseqDataset + ) -> LanguagePairDataset: + return LanguagePairDataset( + src, + src.sizes, + self.dictionary, + tgt=tgt, + tgt_sizes=tgt.sizes, + tgt_dict=self.dictionary, + left_pad_source=self.args.left_pad_source, + left_pad_target=self.args.left_pad_target, + # TODO: should we shuffle ? we are already sorting batch by sizes so ? + # shuffle=True, + ) + + def _prepend_lang_bos_to_target( + self, dataset: LanguagePairDataset, lang: str + ) -> LanguagePairDataset: + bos = _lang_token_index(self.dictionary, lang) + return TransformEosLangPairDataset( + dataset, + src_eos=self.dictionary.eos(), + new_src_eos=self.dictionary.eos(), + tgt_bos=self.dictionary.eos(), + new_tgt_bos=bos, + ) + + def load_bt_dataset(self, data_path: str, lang: str) -> FairseqDataset: + """The BT dataset is generated with (tgt, tgt) pairs. + The actual translation to a (generated_src, tgt) pair + is done on the fly during training. + """ + mono_dataset = data_utils.load_indexed_dataset( + data_path, self.common_dict, self.args.dataset_impl + ) + assert mono_dataset is not None, f"No dataset found for {lang}" + + mono_dataset_src = PrependTokenDataset( + mono_dataset, _lang_token_index(self.dictionary, lang) + ) + + mono_dataset_bt = self._langpair_dataset(mono_dataset_src, mono_dataset) + logger.info( + f"mono_lang = {lang} " + f"lang token index = {_lang_token_index(self.dictionary, lang)} " + f"lang token = {_lang_token(lang)}" + ) + + mono_dataset_bt = self._prepend_lang_bos_to_target(mono_dataset_bt, lang) + return mono_dataset_bt + + def load_denoise_dataset(self, data_path: str, lang: str) -> FairseqDataset: + """Classic denoising dataset""" + dataset = data_utils.load_indexed_dataset( + data_path, self.common_dict, self.args.dataset_impl + ) + noisy_dataset = NoisingDataset( + dataset, + self.dictionary, + seed=1, + max_word_shuffle_distance=self.args.max_word_shuffle_distance, + word_dropout_prob=self.args.word_dropout_prob, + word_blanking_prob=self.args.word_blanking_prob, + ) + noisy_dataset = PrependTokenDataset( + noisy_dataset, _lang_token_index(self.dictionary, lang) + ) + + clean_dataset = data_utils.load_indexed_dataset( + data_path, self.common_dict, self.args.dataset_impl + ) + denoising_dataset = self._langpair_dataset(noisy_dataset, clean_dataset) + denoising_dataset = self._prepend_lang_bos_to_target(denoising_dataset, lang) + return denoising_dataset + + def load_translation_dataset( + self, split: str, data_path: str, combine: bool = False + ): + # only judging with one language pair for the moment, + # since ConcatDataset doesn't work as expected + assert len(self.valid_lang_pairs) == 1, "For now..." + valid_lang_pair = self.valid_lang_pairs[0] + src, tgt = valid_lang_pair.split("-") + + # use the same function than TranslationTask + src_tgt_dt = load_langpair_dataset( + data_path, + split, + src, + self.common_dict, + tgt, + self.common_dict, + combine=combine, + dataset_impl=self.args.dataset_impl, + upsample_primary=self.args.upsample_primary, + left_pad_source=self.args.left_pad_source, + left_pad_target=self.args.left_pad_target, + max_source_positions=self.args.max_source_positions, + max_target_positions=self.args.max_target_positions, + load_alignments=self.args.load_alignments, + truncate_source=self.args.truncate_source, + num_buckets=self.args.num_batch_buckets, + shuffle=(split != "test"), + prepend_bos_src=_lang_token_index(self.dictionary, src), + ) + + src_tgt_eos_dt = self._prepend_lang_bos_to_target(src_tgt_dt, tgt) + src_tgt_eos_dt.args = self.args + return src_tgt_eos_dt + + def build_dataset_for_inference(self, src_tokens, src_lengths, constraints=None): + raise NotImplementedError + + def build_model(self, args, from_checkpoint=False): + # torch.autograd.set_detect_anomaly(True) + model = super().build_model(args, from_checkpoint) + + add_secial_tokens_to_dict_and_model(self.common_dict, model, self.mono_langs) + + self.sequence_generators = {} + for mono_lang in self.mono_langs: + self.sequence_generators[mono_lang] = SequenceGenerator( + [model], + tgt_dict=self.dictionary, + beam_size=1, + max_len_a=1.3, + max_len_b=5, + min_len=5, + # keep 1 to be able to prepend bos + max_len=model.max_decoder_positions() - 1, + ) + + if getattr(args, "eval_bleu", False): + assert getattr(args, "eval_bleu_detok", None) is not None, ( + "--eval-bleu-detok is required if using --eval-bleu; " + "try --eval-bleu-detok=moses (or --eval-bleu-detok=space " + "to disable detokenization, e.g., when using sentencepiece)" + ) + detok_args = json.loads(getattr(args, "eval_bleu_detok_args", "{}") or "{}") + self.tokenizer = encoders.build_tokenizer( + Namespace( + tokenizer=getattr(args, "eval_bleu_detok", None), **detok_args + ) + ) + + gen_args = json.loads(getattr(args, "eval_bleu_args", "{}") or "{}") + self.bleu_sequence_generator = self.build_generator( + [model], Namespace(**gen_args) + ) + + return model + + def max_positions(self): + """Return the max sentence length allowed by the task.""" + return (self.args.max_source_positions, self.args.max_target_positions) + + @property + def dictionary(self): + """Return the source :class:`~fairseq.data.Dictionary`.""" + return self.common_dict + + def display_samples_once_in_a_while(self, smp, mono_lang, other_lang): + self._show_samples_ctr += 1 + if self._show_samples_ctr < self.SHOW_SAMPLES_INTERVAL: + return + self._show_samples_ctr = 0 + + ln = smp["net_input"]["src_tokens"].shape[0] + + logger.info( + f"(r:{self.args.distributed_rank}) : " + f"{other_lang} ---> {mono_lang} " + f"({other_lang} was generated by back-translation.) {ln} samples" + ) + + for i in range(min(ln, self.SHOW_SAMPLES_NUMBER)): + src_tokens = smp["net_input"]["src_tokens"][i] + tgt_tokens = smp["target"][i] + + src_str = self.dictionary.string(src_tokens, "sentencepiece") + tgt_str = self.dictionary.string(tgt_tokens, "sentencepiece") + logger.info( + f"\n{i}\t\t[{other_lang} generated] {src_str}\n" + f"\t\t[{mono_lang} original ] {tgt_str}\n" + f"\t\t[ src tokens] {src_tokens}\n" + ) + + def backtranslate_sample(self, smp, orig_lang, other_lang) -> None: + """ + * WARNING: smp is modified in place. + * At the start of this function, `smp` has the same input and target: + |--------------------------------------------------------| + | smp['net_input']['src_tokens'] | smp['target'] | + | (from data) __en__ hello world | __en__ hello world | + |--------------------------------------------------------| + + * We call generator.generate(smp, bos_token = token("ro")), + and copy the result as input + * At the end, `smp` has the translation to other language. + |--------------------------------------------------------| + | smp['net_input']['src_tokens'] | smp['target'] | + | (generated) __ro__ salut lume | __en__ hello world | + |--------------------------------------------------------| + + """ + bos_token = _lang_token_index(self.dictionary, other_lang) + generated = self.sequence_generators[orig_lang].generate( + models=[], sample=smp, bos_token=bos_token + ) + + max_lngth = max([gn[0]["tokens"].size(0) for gn in generated]) + net_input = smp["net_input"] + n_src_tokens = torch.empty( + size=(len(generated), max_lngth + 1), dtype=net_input["src_tokens"].dtype + ) + n_src_lengths = torch.empty( + len(generated), dtype=net_input["src_lengths"].dtype + ) + + for i, gn in enumerate(generated): + tokens = gn[0]["tokens"] + tokens_size = tokens.size(0) + padding_needed = max_lngth - tokens_size + tokens = torch.cat([tokens.new([bos_token]), tokens]) + tokens = F.pad(tokens, (0, padding_needed), value=self.dictionary.pad()) + n_src_tokens[i] = tokens + n_src_lengths[i] = tokens_size + 1 + + device = net_input["src_tokens"].device + # This seems to be important + del net_input["src_tokens"] + del net_input["src_lengths"] + net_input["src_tokens"] = n_src_tokens.to(device) + net_input["src_lengths"] = n_src_lengths.to(device) + + def generate(self, smp, model): + model.eval() + orig_lang = ( + self.dictionary[smp["net_input"]["src_tokens"][0][0]] + .replace(" ", "") + .replace("_", "") + ) + bos_token = smp["net_input"]["prev_output_tokens"][0][0] + with torch.no_grad(): + generated = self.sequence_generators[orig_lang].generate( + models=[model], sample=smp, bos_token=bos_token + ) + return generated + + def get_other_lang(self, lang): + # TODO: allow more complex mapping + if lang != self.mono_langs[0]: + return self.mono_langs[0] + if len(self.mono_langs) == 2: + return self.mono_langs[1] + return self.mono_langs[np.random.randint(1, len(self.mono_langs))] + + def train_step( + self, sample, model, criterion, optimizer, update_num, ignore_grad=False + ): + + model.train() + model.set_num_updates(update_num) + + agg_loss, agg_sample_size = 0.0, 0.0 + agg_logging_output: Dict[str, float] = defaultdict(float) + + dataset_keys = self.datasets["train"].datasets.keys() + + weights = { + "BT": self.lambda_bt(update_num), + "DENOISE": self.lambda_dae(update_num), + } + log_keys = {"BT": "bt_", "DENOISE": "dae_"} + + for dataset_key in dataset_keys: + smp = sample[dataset_key] + mono_lang, task_subtype = dataset_key.split("-") + if weights[task_subtype] == 0: + continue + + if task_subtype == "BT": + with torch.autograd.profiler.record_function("backtranslation"): + model.eval() + # TODO: Could we translate to several language at once ? + # this would allow to share encoder_out and maximize GPU usage. + other_lang = self.get_other_lang(mono_lang) + self.backtranslate_sample(smp, mono_lang, other_lang) + self.display_samples_once_in_a_while(smp, mono_lang, other_lang) + model.train() + + # Like in FairseqTask.train_step + with torch.autograd.profiler.record_function("forward"): + loss, sample_size, logging_output = criterion(model, smp) + loss *= weights[task_subtype] + if ignore_grad: + loss *= 0 + with torch.autograd.profiler.record_function("backward"): + optimizer.backward(loss) + + agg_loss += loss.item() + agg_sample_size += sample_size + for k in logging_output: + agg_logging_output[log_keys[task_subtype] + k] += logging_output[k] + agg_logging_output[k] += logging_output[k] + + return agg_loss, agg_sample_size, agg_logging_output + + def get_bos_token_from_sample(self, sample): + net_input = sample["net_input"] + source_lang_token_id = torch.unique(net_input["src_tokens"][:, 0]).item() + source_lang_token = self.dictionary[source_lang_token_id].replace("_", "") + target_lang_token_id = _lang_token_index( + self.dictionary, self.get_other_lang(source_lang_token) + ) + + return target_lang_token_id + + def reduce_metrics(self, logging_outputs, criterion): + super().reduce_metrics(logging_outputs, criterion) + bt_sample_size = sum(x.get("bt_sample_size", 0) for x in logging_outputs) + if bt_sample_size: + bt_loss_sum = sum(x.get("bt_loss", 0) for x in logging_outputs) + bt_loss_sum *= 1 / bt_sample_size / math.log(2) + metrics.log_scalar("bt_loss", bt_loss_sum, bt_sample_size, round=3) + + bt_nll_loss_sum = sum(x.get("bt_nll_loss", 0) for x in logging_outputs) + bt_ntokens = sum(x.get("bt_ntokens", 0) for x in logging_outputs) + bt_nll_loss_sum *= 1 / bt_ntokens / math.log(2) + metrics.log_scalar("bt_nll_loss", bt_nll_loss_sum, bt_ntokens, round=3) + metrics.log_derived( + "bt_ppl", lambda meters: utils.get_perplexity(meters["bt_nll_loss"].avg) + ) + + dae_sample_size = sum(x.get("dae_sample_size", 0) for x in logging_outputs) + if dae_sample_size: + dae_loss_sum = sum(x.get("dae_loss", 0) for x in logging_outputs) + dae_loss_sum *= 1 / dae_sample_size / math.log(2) + metrics.log_scalar("dae_loss", dae_loss_sum, dae_sample_size, round=3) + + dae_nll_loss_sum = sum(x.get("dae_nll_loss", 0) for x in logging_outputs) + dae_ntokens = sum(x.get("dae_ntokens", 0) for x in logging_outputs) + dae_nll_loss_sum *= 1 / dae_ntokens / math.log(2) + metrics.log_scalar("dae_nll_loss", dae_nll_loss_sum, dae_ntokens, round=3) + metrics.log_derived( + "dae_ppl", + lambda meters: utils.get_perplexity(meters["dae_nll_loss"].avg), + ) + + +@torch.no_grad() +def extend_embedding( + emb: nn.Module, new_vocab_size: int, copy_from_token_id: int +) -> None: + old_emb_data = emb.weight.data + (old_vocab_size, dim) = old_emb_data.shape + assert new_vocab_size >= old_vocab_size + + if new_vocab_size > old_vocab_size: + emb.weight.data = torch.zeros((new_vocab_size, dim)) + emb.weight.data[:old_vocab_size, :] = old_emb_data + # initialize new embeddings + emb.weight.data[old_vocab_size:, :] = old_emb_data[copy_from_token_id] + if hasattr(emb, "num_embeddings"): + emb.num_embeddings = new_vocab_size + if hasattr(emb, "out_features"): + emb.out_features = new_vocab_size + + if getattr(emb, "bias", None) is None: + return + + # Fix the bias. + # Bias shape can be different from the previous vocab size + # if the weight matrix was shared and alread extended but not the bias. + (old_vocab_size,) = emb.bias.shape + assert new_vocab_size >= old_vocab_size + if new_vocab_size > old_vocab_size: + old_bias = emb.bias.data + new_bias = torch.zeros( + (new_vocab_size,), dtype=old_bias.dtype, device=old_bias.device + ) + new_bias[:old_vocab_size] = old_bias + emb.bias.data = new_bias + + +def add_secial_tokens_to_dict_and_model( + dictionary: "fairseq.data.Dictionary", + model: nn.Module, + mono_langs: Sequence[str], +) -> None: + embs = model.encoder.embed_tokens + vocab_size, embedding_dim = embs.weight.shape + + # The model may or may not have a '' embedding yet + assert ( + len(dictionary) <= vocab_size <= len(dictionary) + 1 + ), f"Dictionary len ({len(dictionary)}) doesn't match embs shape ({embs.weight.shape})" + # TODO: we should reuse the pretrained model dict which already has + dictionary.add_symbol("") + + for lang in mono_langs: + lang_token = _lang_token(lang) + dictionary.add_symbol(lang_token) + logger.info( + f"dictionary: {len(dictionary)} -> {vocab_size} tokens " + f"after adding {len(mono_langs)} lang tokens." + ) + + if len(dictionary) <= vocab_size: + return + + extend_embedding(embs, len(dictionary), dictionary.bos()) + dec_embs = model.decoder.embed_tokens + extend_embedding(dec_embs, len(dictionary), dictionary.bos()) + lm_head = model.decoder.output_projection + extend_embedding(lm_head, len(dictionary), dictionary.bos()) + assert lm_head.weight.shape == (len(dictionary), embedding_dim) + + +def _lang_token(lang: str) -> str: + return f"__{lang}__" + + +def _lang_token_index(dictionary, lang: str) -> int: + return dictionary.index(_lang_token(lang)) + + +@contextlib.contextmanager +def assert_weights_have_changed(model: nn.Module): + def checksum(model: nn.Module) -> float: + return sum(p.sum().item() for p in model.parameters()) + + initial_checksum = checksum(model) + yield model + final_checksum = checksum(model) + logger.info( + f"initial_checksum={initial_checksum} -> final_checksum={final_checksum}" + ) + assert initial_checksum != final_checksum, "Model hasn't changed !" diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/semisupervised_translation.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/semisupervised_translation.py new file mode 100644 index 00000000..432b8a52 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/semisupervised_translation.py @@ -0,0 +1,485 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +from collections import OrderedDict + +from fairseq import utils +from fairseq.data import ( + BacktranslationDataset, + IndexedCachedDataset, + IndexedDataset, + IndexedRawTextDataset, + LanguagePairDataset, + NoisingDataset, + RoundRobinZipDatasets, + data_utils, + indexed_dataset, +) +from fairseq.models import FairseqMultiModel +from fairseq.sequence_generator import SequenceGenerator + +from . import register_task +from .multilingual_translation import MultilingualTranslationTask + + +logger = logging.getLogger(__name__) + + +def _get_bt_dataset_key(lang_pair): + return "bt:" + lang_pair + + +def _get_denoising_dataset_key(lang_pair): + return "denoising:" + lang_pair + + +# ported from UnsupervisedMT +def parse_lambda_config(x): + """ + Parse the configuration of lambda coefficient (for scheduling). + x = "3" # lambda will be a constant equal to x + x = "0:1,1000:0" # lambda will start from 1 and linearly decrease + # to 0 during the first 1000 iterations + x = "0:0,1000:0,2000:1" # lambda will be equal to 0 for the first 1000 + # iterations, then will linearly increase to 1 until iteration 2000 + """ + split = x.split(",") + if len(split) == 1: + return float(x), None + else: + split = [s.split(os.pathsep) for s in split] + assert all(len(s) == 2 for s in split) + assert all(k.isdigit() for k, _ in split) + assert all( + int(split[i][0]) < int(split[i + 1][0]) for i in range(len(split) - 1) + ) + return float(split[0][1]), [(int(k), float(v)) for k, v in split] + + +@register_task("semisupervised_translation") +class SemisupervisedTranslationTask(MultilingualTranslationTask): + """A task for training multiple translation models simultaneously. + + We iterate round-robin over batches from multiple language pairs, ordered + according to the `--lang-pairs` argument. + + The training loop is roughly: + + for i in range(len(epoch)): + for lang_pair in args.lang_pairs: + batch = next_batch_for_lang_pair(lang_pair) + loss = criterion(model_for_lang_pair(lang_pair), batch) + loss.backward() + optimizer.step() + + In practice, `next_batch_for_lang_pair` is abstracted in a FairseqDataset + (e.g., `RoundRobinZipDatasets`) and `model_for_lang_pair` is a model that + implements the `FairseqMultiModel` interface. + + During inference it is required to specify a single `--source-lang` and + `--target-lang`, instead of `--lang-pairs`. + """ + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + # fmt: off + MultilingualTranslationTask.add_args(parser) + parser.add_argument('--lambda-parallel-config', default="1.0", type=str, metavar='CONFIG', + help='cross-entropy reconstruction coefficient (parallel data). ' + 'use fixed weight during training if set to floating point number. ' + 'use piecewise linear function over number of updates to schedule the ' + 'weight with the format: w0:step0,w1:step1,...') + parser.add_argument('--lambda-denoising-config', default="0.0", type=str, metavar='CONFIG', + help='Cross-entropy reconstruction coefficient (denoising autoencoding)' + 'use fixed weight during training if set to floating point number. ' + 'use piecewise linear function over number of updates to schedule the ' + 'weight with the format: w0:step0,w1:step1,...') + parser.add_argument('--lambda-otf-bt-config', default="0.0", type=str, metavar='CONFIG', + help='cross-entropy reconstruction coefficient (on-the-fly back-translation parallel data)' + 'use fixed weight during training if set to floating point number. ' + 'use piecewise linear function over number of updates to schedule the ' + 'weight with the format: w0:step0,w1:step1,...') + parser.add_argument('--bt-max-len-a', default=1.1, type=float, metavar='N', + help='generate back-translated sequences of maximum length ax + b, where x is the ' + 'source length') + parser.add_argument('--bt-max-len-b', default=10.0, type=float, metavar='N', + help='generate back-translated sequences of maximum length ax + b, where x is the ' + 'source length') + parser.add_argument('--bt-beam-size', default=1, type=int, metavar='N', + help='beam size used in beam search of online back-translation') + parser.add_argument('--max-word-shuffle-distance', default=3.0, type=float, metavar='N', + help='maximum word shuffle distance for denoising autoencoding data generation') + parser.add_argument('--word-dropout-prob', default=0.1, type=float, metavar='N', + help='word dropout probability for denoising autoencoding data generation') + parser.add_argument('--word-blanking-prob', default=0.2, type=float, metavar='N', + help='word blanking probability for denoising autoencoding data generation') + # fmt: on + + def __init__(self, args, dicts, training): + super().__init__(args, dicts, training) + self.lambda_parallel, self.lambda_parallel_steps = parse_lambda_config( + args.lambda_parallel_config + ) + self.lambda_otf_bt, self.lambda_otf_bt_steps = parse_lambda_config( + args.lambda_otf_bt_config + ) + self.lambda_denoising, self.lambda_denoising_steps = parse_lambda_config( + args.lambda_denoising_config + ) + if self.lambda_denoising > 0.0 or self.lambda_denoising_steps is not None: + denoising_lang_pairs = [ + "%s-%s" % (tgt, tgt) + for tgt in {lang_pair.split("-")[1] for lang_pair in args.lang_pairs} + ] + self.model_lang_pairs = self.model_lang_pairs + denoising_lang_pairs + self.backtranslate_datasets = {} + self.backtranslators = {} + + @classmethod + def setup_task(cls, args, **kwargs): + dicts, training = MultilingualTranslationTask.prepare(args, **kwargs) + return cls(args, dicts, training) + + def load_dataset(self, split, epoch=1, **kwargs): + """Load a dataset split.""" + paths = utils.split_paths(self.args.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + + def split_exists(split, src, tgt, lang): + if src is not None: + filename = os.path.join( + data_path, "{}.{}-{}.{}".format(split, src, tgt, lang) + ) + else: + filename = os.path.join( + data_path, "{}.{}-None.{}".format(split, src, tgt) + ) + return indexed_dataset.dataset_exists(filename, impl=self.args.dataset_impl) + + def load_indexed_dataset(path, dictionary): + return data_utils.load_indexed_dataset( + path, dictionary, self.args.dataset_impl + ) + + # load parallel datasets + src_datasets, tgt_datasets = {}, {} + if ( + self.lambda_parallel > 0.0 + or self.lambda_parallel_steps is not None + or not split.startswith("train") + ): + for lang_pair in self.lang_pairs: + src, tgt = lang_pair.split("-") + if split_exists(split, src, tgt, src): + prefix = os.path.join( + data_path, "{}.{}-{}.".format(split, src, tgt) + ) + elif split_exists(split, tgt, src, src): + prefix = os.path.join( + data_path, "{}.{}-{}.".format(split, tgt, src) + ) + else: + continue + src_datasets[lang_pair] = load_indexed_dataset( + prefix + src, self.dicts[src] + ) + tgt_datasets[lang_pair] = load_indexed_dataset( + prefix + tgt, self.dicts[tgt] + ) + logger.info( + "parallel-{} {} {} examples".format( + data_path, split, len(src_datasets[lang_pair]) + ) + ) + if len(src_datasets) == 0: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, data_path) + ) + + # back translation datasets + backtranslate_datasets = {} + if ( + self.lambda_otf_bt > 0.0 or self.lambda_otf_bt_steps is not None + ) and split.startswith("train"): + for lang_pair in self.lang_pairs: + src, tgt = lang_pair.split("-") + if not split_exists(split, tgt, None, tgt): + raise FileNotFoundError( + "Dataset not found: backtranslation {} ({})".format( + split, data_path + ) + ) + filename = os.path.join( + data_path, "{}.{}-None.{}".format(split, tgt, tgt) + ) + dataset = load_indexed_dataset(filename, self.dicts[tgt]) + lang_pair_dataset_tgt = LanguagePairDataset( + dataset, + dataset.sizes, + self.dicts[tgt], + left_pad_source=self.args.left_pad_source, + left_pad_target=self.args.left_pad_target, + ) + lang_pair_dataset = LanguagePairDataset( + dataset, + dataset.sizes, + src_dict=self.dicts[src], + tgt=dataset, + tgt_sizes=dataset.sizes, + tgt_dict=self.dicts[tgt], + left_pad_source=self.args.left_pad_source, + left_pad_target=self.args.left_pad_target, + ) + backtranslate_datasets[lang_pair] = BacktranslationDataset( + tgt_dataset=self.alter_dataset_langtok( + lang_pair_dataset_tgt, + src_eos=self.dicts[tgt].eos(), + src_lang=tgt, + tgt_lang=src, + ), + backtranslation_fn=self.backtranslators[lang_pair], + src_dict=self.dicts[src], + tgt_dict=self.dicts[tgt], + output_collater=self.alter_dataset_langtok( + lang_pair_dataset=lang_pair_dataset, + src_eos=self.dicts[src].eos(), + src_lang=src, + tgt_eos=self.dicts[tgt].eos(), + tgt_lang=tgt, + ).collater, + ) + logger.info( + "backtranslate-{}: {} {} {} examples".format( + tgt, + data_path, + split, + len(backtranslate_datasets[lang_pair]), + ) + ) + self.backtranslate_datasets[lang_pair] = backtranslate_datasets[ + lang_pair + ] + + # denoising autoencoder + noising_datasets = {} + if ( + self.lambda_denoising > 0.0 or self.lambda_denoising_steps is not None + ) and split.startswith("train"): + for lang_pair in self.lang_pairs: + _, tgt = lang_pair.split("-") + if not split_exists(split, tgt, None, tgt): + continue + filename = os.path.join( + data_path, "{}.{}-None.{}".format(split, tgt, tgt) + ) + tgt_dataset1 = load_indexed_dataset(filename, self.dicts[tgt]) + tgt_dataset2 = load_indexed_dataset(filename, self.dicts[tgt]) + noising_dataset = NoisingDataset( + tgt_dataset1, + self.dicts[tgt], + seed=1, + max_word_shuffle_distance=self.args.max_word_shuffle_distance, + word_dropout_prob=self.args.word_dropout_prob, + word_blanking_prob=self.args.word_blanking_prob, + ) + noising_datasets[lang_pair] = self.alter_dataset_langtok( + LanguagePairDataset( + noising_dataset, + tgt_dataset1.sizes, + self.dicts[tgt], + tgt_dataset2, + tgt_dataset2.sizes, + self.dicts[tgt], + left_pad_source=self.args.left_pad_source, + left_pad_target=self.args.left_pad_target, + ), + src_eos=self.dicts[tgt].eos(), + src_lang=tgt, + tgt_eos=self.dicts[tgt].eos(), + tgt_lang=tgt, + ) + logger.info( + "denoising-{}: {} {} {} examples".format( + tgt, + data_path, + split, + len(noising_datasets[lang_pair]), + ) + ) + + def language_pair_dataset(lang_pair): + src, tgt = lang_pair.split("-") + src_dataset, tgt_dataset = src_datasets[lang_pair], tgt_datasets[lang_pair] + return self.alter_dataset_langtok( + LanguagePairDataset( + src_dataset, + src_dataset.sizes, + self.dicts[src], + tgt_dataset, + tgt_dataset.sizes, + self.dicts[tgt], + left_pad_source=self.args.left_pad_source, + left_pad_target=self.args.left_pad_target, + ), + self.dicts[src].eos(), + src, + self.dicts[tgt].eos(), + tgt, + ) + + self.datasets[split] = RoundRobinZipDatasets( + OrderedDict( + [ + (lang_pair, language_pair_dataset(lang_pair)) + for lang_pair in src_datasets.keys() + ] + + [ + (_get_bt_dataset_key(lang_pair), dataset) + for lang_pair, dataset in backtranslate_datasets.items() + ] + + [ + (_get_denoising_dataset_key(lang_pair), dataset) + for lang_pair, dataset in noising_datasets.items() + ] + ), + eval_key=None + if self.training + else "%s-%s" % (self.args.source_lang, self.args.target_lang), + ) + + def build_model(self, args, from_checkpoint=False): + from fairseq import models + + model = models.build_model(args, self, from_checkpoint) + if not isinstance(model, FairseqMultiModel): + raise ValueError( + "SemisupervisedTranslationTask requires a FairseqMultiModel architecture" + ) + + # create SequenceGenerator for each model that has backtranslation dependency on it + self.sequence_generators = {} + if ( + self.lambda_otf_bt > 0.0 or self.lambda_otf_bt_steps is not None + ) and self.training: + for lang_pair in self.lang_pairs: + src, tgt = lang_pair.split("-") + key = "{}-{}".format(tgt, src) + self.sequence_generators[key] = SequenceGenerator( + [model.models[key]], + tgt_dict=self.dicts[src], + beam_size=args.bt_beam_size, + max_len_a=args.bt_max_len_a, + max_len_b=args.bt_max_len_b, + ) + decoder_lang_tok_idx = self.get_decoder_langtok(src) + + def backtranslate_fn( + sample, + model=model.models[key], + bos_token=decoder_lang_tok_idx, + sequence_generator=self.sequence_generators[key], + ): + return sequence_generator.generate( + [model], + sample, + bos_token=bos_token, + ) + + self.backtranslators[lang_pair] = backtranslate_fn + + return model + + def train_step( + self, sample, model, criterion, optimizer, update_num, ignore_grad=False + ): + model.train() + + if update_num > 0: + self.update_step(update_num) + + agg_loss, agg_sample_size, agg_logging_output = 0.0, 0.0, {} + + def forward_backward(model, samples, logging_output_key, weight): + nonlocal agg_loss, agg_sample_size, agg_logging_output + if samples is None or len(samples) == 0: + return + loss, sample_size, logging_output = criterion(model, samples) + if ignore_grad: + loss *= 0 + else: + loss *= weight + optimizer.backward(loss) + agg_loss += loss.detach().item() + # TODO make summing of the sample sizes configurable + agg_sample_size += sample_size + for k in logging_output: + agg_logging_output[k] += logging_output[k] + agg_logging_output[logging_output_key] += logging_output[k] + + if self.lambda_parallel > 0.0: + for lang_pair in self.lang_pairs: + forward_backward( + model.models[lang_pair], + sample[lang_pair], + lang_pair, + self.lambda_parallel, + ) + + if self.lambda_otf_bt > 0.0: + for lang_pair in self.lang_pairs: + sample_key = _get_bt_dataset_key(lang_pair) + forward_backward( + model.models[lang_pair], + sample[sample_key], + sample_key, + self.lambda_otf_bt, + ) + + if self.lambda_denoising > 0.0: + for lang_pair in self.lang_pairs: + _, tgt = lang_pair.split("-") + sample_key = _get_denoising_dataset_key(lang_pair) + forward_backward( + model.models["{0}-{0}".format(tgt)], + sample[sample_key], + sample_key, + self.lambda_denoising, + ) + + return agg_loss, agg_sample_size, agg_logging_output + + def update_step(self, num_updates): + def lambda_step_func(config, n_iter): + """ + Update a lambda value according to its schedule configuration. + """ + ranges = [ + i + for i in range(len(config) - 1) + if config[i][0] <= n_iter < config[i + 1][0] + ] + if len(ranges) == 0: + assert n_iter >= config[-1][0] + return config[-1][1] + assert len(ranges) == 1 + i = ranges[0] + x_a, y_a = config[i] + x_b, y_b = config[i + 1] + return y_a + (n_iter - x_a) * float(y_b - y_a) / float(x_b - x_a) + + if self.lambda_parallel_steps is not None: + self.lambda_parallel = lambda_step_func( + self.lambda_parallel_steps, num_updates + ) + if self.lambda_denoising_steps is not None: + self.lambda_denoising = lambda_step_func( + self.lambda_denoising_steps, num_updates + ) + if self.lambda_otf_bt_steps is not None: + self.lambda_otf_bt = lambda_step_func(self.lambda_otf_bt_steps, num_updates) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_prediction.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_prediction.py new file mode 100644 index 00000000..52532ff6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_prediction.py @@ -0,0 +1,286 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os + +import contextlib +from dataclasses import dataclass, field +from typing import Optional +from omegaconf import MISSING, II, open_dict, OmegaConf + +import numpy as np +from fairseq.data import ( + ConcatSentencesDataset, + Dictionary, + IdDataset, + NestedDictionaryDataset, + NumelDataset, + NumSamplesDataset, + OffsetTokensDataset, + PrependTokenDataset, + RawLabelDataset, + RightPadDataset, + RollDataset, + SortDataset, + StripTokenDataset, + data_utils, +) +from fairseq.data.shorten_dataset import maybe_shorten_dataset +from fairseq.tasks import FairseqDataclass, FairseqTask, register_task +from fairseq.dataclass import ChoiceEnum + + +logger = logging.getLogger(__name__) +SHORTEN_METHOD_CHOICES = ChoiceEnum(["none", "truncate", "random_crop"]) + + +@dataclass +class SentencePredictionConfig(FairseqDataclass): + data: str = field(default=MISSING, metadata={"help": "path to data directory"}) + num_classes: int = field( + default=-1, + metadata={"help": "number of classes or regression targets"}, + ) + init_token: Optional[int] = field( + default=None, + metadata={"help": "add token at the beginning of each batch item"}, + ) + separator_token: Optional[int] = field( + default=None, + metadata={"help": "add separator token between inputs"}, + ) + no_shuffle: bool = field( + default=False, + ) + shorten_method: SHORTEN_METHOD_CHOICES = field( + default="none", + metadata={ + "help": "if not none, shorten sequences that exceed tokens_per_sample" + }, + ) + shorten_data_split_list: str = field( + default="", + metadata={ + "help": "comma-separated list of dataset splits to apply shortening to, " + 'e.g., "train,valid" (default: all dataset splits)' + }, + ) + add_prev_output_tokens: bool = field( + default=False, + metadata={ + "help": "add prev_output_tokens to sample, used for encoder-decoder arch" + }, + ) + max_positions: int = field( + default=512, + metadata={"help": "max tokens per example"}, + ) + + regression_target: bool = II("criterion.regression_target") + classification_head_name: str = II("criterion.classification_head_name") + seed: int = II("common.seed") + + +@register_task("sentence_prediction", dataclass=SentencePredictionConfig) +class SentencePredictionTask(FairseqTask): + """ + Sentence (or sentence pair) prediction (classification or regression) task. + + Args: + dictionary (Dictionary): the dictionary for the input of the task + """ + + def __init__(self, cfg, data_dictionary, label_dictionary): + super().__init__(cfg) + self.dictionary = data_dictionary + self._label_dictionary = label_dictionary + + @classmethod + def load_dictionary(cls, filename): + """Load the dictionary from the filename + + Args: + filename (str): the filename + """ + dictionary = Dictionary.load(filename) + dictionary.add_symbol("") + return dictionary + + @classmethod + def setup_task(cls, cfg, **kwargs): + assert cfg.num_classes > 0, "Must set task.num_classes" + + # load data dictionary + data_dict = cls.load_dictionary( + os.path.join(cfg.data, "input0", "dict.txt"), + ) + logger.info("[input] dictionary: {} types".format(len(data_dict))) + + # load label dictionary + if not cfg.regression_target: + label_dict = cls.load_dictionary( + os.path.join(cfg.data, "label", "dict.txt"), + ) + logger.info("[label] dictionary: {} types".format(len(label_dict))) + else: + label_dict = data_dict + return cls(cfg, data_dict, label_dict) + + def load_dataset(self, split, combine=False, **kwargs): + """Load a given dataset split (e.g., train, valid, test).""" + + def get_path(key, split): + return os.path.join(self.cfg.data, key, split) + + def make_dataset(key, dictionary): + split_path = get_path(key, split) + + try: + dataset = data_utils.load_indexed_dataset( + split_path, + dictionary, + combine=combine, + ) + except Exception as e: + if "StorageException: [404] Path not found" in str(e): + logger.warning(f"dataset {e} not found") + dataset = None + else: + raise e + return dataset + + input0 = make_dataset("input0", self.source_dictionary) + assert input0 is not None, "could not find dataset: {}".format( + get_path("input0", split) + ) + input1 = make_dataset("input1", self.source_dictionary) + + if self.cfg.init_token is not None: + input0 = PrependTokenDataset(input0, self.cfg.init_token) + + if input1 is None: + src_tokens = input0 + else: + if self.cfg.separator_token is not None: + input1 = PrependTokenDataset(input1, self.cfg.separator_token) + + src_tokens = ConcatSentencesDataset(input0, input1) + + with data_utils.numpy_seed(self.cfg.seed): + shuffle = np.random.permutation(len(src_tokens)) + + src_tokens = maybe_shorten_dataset( + src_tokens, + split, + self.cfg.shorten_data_split_list, + self.cfg.shorten_method, + self.max_positions(), + self.cfg.seed, + ) + + dataset = { + "id": IdDataset(), + "net_input": { + "src_tokens": RightPadDataset( + src_tokens, + pad_idx=self.source_dictionary.pad(), + ), + "src_lengths": NumelDataset(src_tokens, reduce=False), + }, + "nsentences": NumSamplesDataset(), + "ntokens": NumelDataset(src_tokens, reduce=True), + } + + if self.cfg.add_prev_output_tokens: + prev_tokens_dataset = RightPadDataset( + RollDataset(src_tokens, 1), + pad_idx=self.dictionary.pad(), + ) + dataset["net_input"].update( + prev_output_tokens=prev_tokens_dataset, + ) + + if not self.cfg.regression_target: + label_dataset = make_dataset("label", self.label_dictionary) + if label_dataset is not None: + dataset.update( + target=OffsetTokensDataset( + StripTokenDataset( + label_dataset, + id_to_strip=self.label_dictionary.eos(), + ), + offset=-self.label_dictionary.nspecial, + ) + ) + else: + label_path = "{0}.label".format(get_path("label", split)) + if os.path.exists(label_path): + + def parse_regression_target(i, line): + values = line.split() + assert ( + len(values) == self.cfg.num_classes + ), f'expected num_classes={self.cfg.num_classes} regression target values on line {i}, found: "{line}"' + return [float(x) for x in values] + + with open(label_path) as h: + dataset.update( + target=RawLabelDataset( + [ + parse_regression_target(i, line.strip()) + for i, line in enumerate(h.readlines()) + ] + ) + ) + + nested_dataset = NestedDictionaryDataset( + dataset, + sizes=[src_tokens.sizes], + ) + + if self.cfg.no_shuffle: + dataset = nested_dataset + else: + dataset = SortDataset( + nested_dataset, + # shuffle + sort_order=[shuffle], + ) + + logger.info("Loaded {0} with #samples: {1}".format(split, len(dataset))) + + self.datasets[split] = dataset + return self.datasets[split] + + def build_model(self, cfg, from_checkpoint=False): + from fairseq import models + + with open_dict(cfg) if OmegaConf.is_config(cfg) else contextlib.ExitStack(): + cfg.max_positions = self.cfg.max_positions + + model = models.build_model(cfg, self, from_checkpoint) + + model.register_classification_head( + self.cfg.classification_head_name, + num_classes=self.cfg.num_classes, + ) + + return model + + def max_positions(self): + return self.cfg.max_positions + + @property + def source_dictionary(self): + return self.dictionary + + @property + def target_dictionary(self): + return self.dictionary + + @property + def label_dictionary(self): + return self._label_dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_prediction_adapters.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_prediction_adapters.py new file mode 100644 index 00000000..afe55696 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_prediction_adapters.py @@ -0,0 +1,56 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging + +import contextlib +from omegaconf import open_dict, OmegaConf + +from fairseq.tasks import register_task +from fairseq.tasks.sentence_prediction import ( + SentencePredictionTask, + SentencePredictionConfig, +) + + +logger = logging.getLogger(__name__) + + +@register_task("sentence_prediction_adapters", dataclass=SentencePredictionConfig) +class SentencePredictionAdapterTask(SentencePredictionTask): + def build_model(self, cfg): + from fairseq import models + + with open_dict(cfg) if OmegaConf.is_config(cfg) else contextlib.ExitStack(): + cfg.max_positions = self.cfg.max_positions + + model = models.build_model(cfg, self) + + model.register_classification_head( + self.cfg.classification_head_name, + num_classes=self.cfg.num_classes, + ) + + logger.info("Freezing Embedding Parameters") + for parameter in model.encoder.sentence_encoder.embed_positions.parameters(): + parameter.requires_grad = False + for ( + parameter + ) in model.encoder.sentence_encoder.layernorm_embedding.parameters(): + parameter.requires_grad = False + for parameter in model.encoder.sentence_encoder.embed_tokens.parameters(): + parameter.requires_grad = False + + logger.info("Freezing Adapters") + for k, v in model.encoder.sentence_encoder.layers._modules.items(): + logger.info("Freezing Adapters in Layer " + str(k)) + if hasattr(v, "adapter_layer_norm"): + logger.info("Freezing Adapter LN") + for parameter in v.adapter_layer_norm.parameters(): + parameter.requires_grad = False + for parameter in v.adapter_modules.parameters(): + parameter.requires_grad = False + + return model diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_ranking.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_ranking.py new file mode 100644 index 00000000..57f63aab --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/sentence_ranking.py @@ -0,0 +1,219 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os + +import numpy as np +from fairseq import utils +from fairseq.data import ( + ConcatSentencesDataset, + Dictionary, + IdDataset, + NestedDictionaryDataset, + NumelDataset, + NumSamplesDataset, + PrependTokenDataset, + RawLabelDataset, + RightPadDataset, + SortDataset, + TruncateDataset, + data_utils, +) +from fairseq.data.shorten_dataset import maybe_shorten_dataset +from fairseq.tasks import LegacyFairseqTask, register_task + + +logger = logging.getLogger(__name__) + + +@register_task("sentence_ranking") +class SentenceRankingTask(LegacyFairseqTask): + """ + Ranking task on multiple sentences. + + Args: + dictionary (Dictionary): the dictionary for the input of the task + """ + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + parser.add_argument("data", metavar="FILE", help="file prefix for data") + parser.add_argument( + "--num-classes", type=int, help="number of sentences to be ranked" + ) + parser.add_argument( + "--init-token", + type=int, + help="add token at the beginning of each batch item", + ) + parser.add_argument( + "--separator-token", type=int, help="add separator token between inputs" + ) + parser.add_argument("--no-shuffle", action="store_true") + parser.add_argument( + "--shorten-method", + default="none", + choices=["none", "truncate", "random_crop"], + help="if not none, shorten sequences that exceed --tokens-per-sample", + ) + parser.add_argument( + "--shorten-data-split-list", + default="", + help="comma-separated list of dataset splits to apply shortening to, " + 'e.g., "train,valid" (default: all dataset splits)', + ) + parser.add_argument( + "--max-option-length", type=int, help="max length for each option" + ) + + def __init__(self, args, dictionary): + super().__init__(args) + self.dictionary = dictionary + + @classmethod + def load_dictionary(cls, args, filename, source=True): + """Load the dictionary from the filename + + Args: + filename (str): the filename + """ + dictionary = Dictionary.load(filename) + dictionary.add_symbol("") + return dictionary + + @classmethod + def setup_task(cls, args, **kwargs): + assert ( + args.criterion == "sentence_ranking" + ), "Must set --criterion=sentence_ranking" + + # load data dictionary + data_dict = cls.load_dictionary( + args, + os.path.join(args.data, "input0", "dict.txt"), + source=True, + ) + logger.info("[input] dictionary: {} types".format(len(data_dict))) + return SentenceRankingTask(args, data_dict) + + def load_dataset(self, split, combine=False, **kwargs): + """Load a given dataset split (e.g., train, valid, test).""" + + def get_path(type, split): + return os.path.join(self.args.data, type, split) + + def make_dataset(type, dictionary): + split_path = get_path(type, split) + + dataset = data_utils.load_indexed_dataset( + split_path, + self.source_dictionary, + self.args.dataset_impl, + combine=combine, + ) + return dataset + + input0 = make_dataset("input0", self.source_dictionary) + input_options = [ + make_dataset("input{idx}".format(idx=idx + 1), self.source_dictionary) + for idx in range(self.args.num_classes) + ] + + if self.args.separator_token is not None: + input0 = PrependTokenDataset(input0, self.args.separator_token) + + src_tokens = [] + for input_option in input_options: + if self.args.init_token is not None: + input_option = PrependTokenDataset(input_option, self.args.init_token) + if self.args.max_option_length is not None: + input_option = TruncateDataset( + input_option, self.args.max_option_length + ) + src_token = ConcatSentencesDataset(input_option, input0) + src_token = maybe_shorten_dataset( + src_token, + split, + self.args.shorten_data_split_list, + self.args.shorten_method, + self.args.max_positions, + self.args.seed, + ) + src_tokens.append(src_token) + + with data_utils.numpy_seed(self.args.seed): + shuffle = np.random.permutation(len(src_tokens[0])) + + dataset = { + "id": IdDataset(), + "nsentences": NumSamplesDataset(), + "ntokens": NumelDataset(src_tokens[0], reduce=True), + } + + for src_token_idx in range(len(src_tokens)): + dataset.update( + { + "net_input{idx}".format(idx=src_token_idx + 1): { + "src_tokens": RightPadDataset( + src_tokens[src_token_idx], + pad_idx=self.source_dictionary.pad(), + ), + "src_lengths": NumelDataset( + src_tokens[src_token_idx], reduce=False + ), + } + } + ) + + label_path = "{}.label".format(get_path("label", split)) + if os.path.exists(label_path): + with open(label_path) as h: + dataset.update( + target=RawLabelDataset([int(x.strip()) for x in h.readlines()]) + ) + + nested_dataset = NestedDictionaryDataset( + dataset, + sizes=[np.maximum.reduce([src_token.sizes for src_token in src_tokens])], + ) + + if self.args.no_shuffle: + dataset = nested_dataset + else: + dataset = SortDataset( + nested_dataset, + # shuffle + sort_order=[shuffle], + ) + + logger.info("Loaded {0} with #samples: {1}".format(split, len(dataset))) + + self.datasets[split] = dataset + return self.datasets[split] + + def build_model(self, args, from_checkpoint=False): + from fairseq import models + + model = models.build_model(args, self, from_checkpoint) + + model.register_classification_head( + getattr(args, "ranking_head_name", "sentence_classification_head"), + num_classes=1, + ) + + return model + + def max_positions(self): + return self.args.max_positions + + @property + def source_dictionary(self): + return self.dictionary + + @property + def target_dictionary(self): + return self.dictionary diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/simultaneous_translation.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/simultaneous_translation.py new file mode 100644 index 00000000..9576b268 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/simultaneous_translation.py @@ -0,0 +1,41 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from fairseq.tasks import register_task +from fairseq.tasks.speech_to_text import SpeechToTextTask +from fairseq.tasks.translation import TranslationTask, TranslationConfig + +try: + import examples.simultaneous_translation # noqa + + import_successful = True +except BaseException: + import_successful = False + + +logger = logging.getLogger(__name__) + + +def check_import(flag): + if not flag: + raise ImportError( + "'examples.simultaneous_translation' is not correctly imported. " + "Please considering `pip install -e $FAIRSEQ_DIR`." + ) + + +@register_task("simul_speech_to_text") +class SimulSpeechToTextTask(SpeechToTextTask): + def __init__(self, args, tgt_dict): + check_import(import_successful) + super().__init__(args, tgt_dict) + + +@register_task("simul_text_to_text", dataclass=TranslationConfig) +class SimulTextToTextTask(TranslationTask): + def __init__(self, cfg, src_dict, tgt_dict): + check_import(import_successful) + super().__init__(cfg, src_dict, tgt_dict) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_to_speech.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_to_speech.py new file mode 100644 index 00000000..d9e23256 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_to_speech.py @@ -0,0 +1,520 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import json +import logging +import math +from argparse import Namespace +from pathlib import Path + +import torch +import torch.nn as nn + +from fairseq import utils +from fairseq.data import Dictionary +from fairseq.data.audio.data_cfg import MultitaskConfig, S2SDataConfig +from fairseq.data.audio.speech_to_speech_dataset import SpeechToSpeechDatasetCreator +from fairseq.data.audio.speech_to_text_dataset import SpeechToTextDataset +from fairseq.tasks import LegacyFairseqTask, register_task +from fairseq.tasks.text_to_speech import batch_mel_cepstral_distortion + +logger = logging.getLogger(__name__) + + +class StackUnitSequenceGenerator(nn.Module): + def __init__(self, tgt_dict, vocab_size): + super().__init__() + self.pad = tgt_dict.pad() + self.eos = tgt_dict.eos() + self.unk = tgt_dict.unk() + self.offset = len(tgt_dict) - vocab_size + self.vocab_size = vocab_size + + def pack_units(self, input: torch.Tensor, n_frames_per_step) -> torch.Tensor: + if n_frames_per_step <= 1: + return input + + bsz, _, n = input.shape + assert n == n_frames_per_step + + scale = [ + pow(self.vocab_size, n_frames_per_step - 1 - i) + for i in range(n_frames_per_step) + ] + scale = torch.LongTensor(scale).squeeze(0).to(input.device) + mask = input >= self.offset + res = ((input - self.offset) * scale * mask).sum(dim=2) + self.offset + return res + + @torch.no_grad() + def generate(self, models, sample, **kwargs): + # currently only support viterbi search for stacked units + model = models[0] + model.eval() + + max_len = model.max_decoder_positions() + # TODO: incorporate max_len_a and max_len_b + + src_tokens = sample["net_input"]["src_tokens"] + src_lengths = sample["net_input"]["src_lengths"] + bsz, src_len, _ = src_tokens.size() + n_frames_per_step = model.decoder.n_frames_per_step + + # initialize + encoder_out = model.forward_encoder( + src_tokens, src_lengths, speaker=sample["speaker"] + ) + incremental_state = {} + pred_out, attn, scores = [], [], [] + finished = src_tokens.new_zeros((bsz,)).bool() + + prev_output_tokens = src_lengths.new_zeros((bsz, 1)).long().fill_(self.eos) + for _ in range(max_len): + cur_out, cur_extra = model.forward_decoder( + prev_output_tokens, + encoder_out=encoder_out, + incremental_state=incremental_state, + ) + + lprobs = model.get_normalized_probs([cur_out], log_probs=True) + # never select pad, unk + lprobs[:, :, self.pad] = -math.inf + lprobs[:, :, self.unk] = -math.inf + + cur_pred_lprob, cur_pred_out = torch.max(lprobs, dim=2) + scores.append(cur_pred_lprob) + pred_out.append(cur_pred_out) + + prev_output_tokens = torch.cat( + ( + prev_output_tokens, + self.pack_units( + cur_pred_out.view(bsz, 1, n_frames_per_step), n_frames_per_step + ), + ), + dim=1, + ) + + attn.append(cur_extra["attn"][0]) + + cur_finished = torch.any(cur_pred_out.squeeze(1) == self.eos, dim=1) + finished = finished | cur_finished + if finished.sum().item() == bsz: + break + + pred_out = torch.cat(pred_out, dim=1).view(bsz, -1) + attn = torch.cat(attn, dim=2) + alignment = attn.max(dim=1)[1] + attn = attn.repeat_interleave(n_frames_per_step, dim=2) + alignment = alignment.repeat_interleave(n_frames_per_step, dim=1) + scores = torch.cat(scores, dim=1) + eos_idx = (pred_out == self.eos).nonzero(as_tuple=True) + out_lens = src_lengths.new_zeros((bsz,)).long().fill_(max_len) + for b, l in zip(eos_idx[0], eos_idx[1]): + out_lens[b] = min(l, out_lens[b]) + + hypos = [ + [ + { + "tokens": pred_out[b, :out_len], + "attn": attn[b, :, :out_len], + "alignment": alignment[b, :out_len], + "positional_scores": scores[b, :out_len], + "score": utils.item(scores[b, :out_len].sum().data), + } + ] + for b, out_len in zip(range(bsz), out_lens) + ] + + return hypos + + +@register_task("speech_to_speech") +class SpeechToSpeechTask(LegacyFairseqTask): + @classmethod + def add_args(cls, parser): + parser.add_argument("data", help="manifest root path") + parser.add_argument( + "--config-yaml", + type=str, + default="config.yaml", + help="Configuration YAML filename (under manifest root)", + ) + parser.add_argument( + "--max-source-positions", + default=6000, + type=int, + metavar="N", + help="max number of tokens in the source sequence", + ) + parser.add_argument( + "--max-target-positions", + default=1024, + type=int, + metavar="N", + help="max number of tokens in the target sequence", + ) + parser.add_argument( + "--target-is-code", + action="store_true", + help="set if target is discrete unit instead of spectrogram", + ) + parser.add_argument( + "--target-code-size", type=int, default=None, help="# discrete units" + ) + parser.add_argument( + "--n-frames-per-step", + type=int, + default=1, + help="# stacked frames, use 0 for reduced discrete unit sequence", + ) + parser.add_argument( + "--multitask-config-yaml", + type=str, + default=None, + help="Configuration YAML filename for the multitasks (under manifest root)", + ) + parser.add_argument("--eval-inference", action="store_true") + parser.add_argument( + "--eval-args", + type=str, + default="{}", + help='generation args for speech-to-unit model , e.g., \'{"beam": 5, "max_len_a": 1}\', as JSON string', + ) + parser.add_argument("--eos-prob-threshold", type=float, default=0.5) + parser.add_argument( + "--mcd-normalize-type", + type=str, + default="targ", + choices=["targ", "pred", "path"], + ) + parser.add_argument( + "--vocoder", + type=str, + default="griffin_lim", + choices=["griffin_lim", "hifigan", "code_hifigan"], + ) + parser.add_argument("--spec-bwd-max-iter", type=int, default=8) + parser.add_argument( + "--infer-target-lang", + type=str, + default="", + help="target language for inference", + ) + + def __init__(self, args, tgt_dict, infer_tgt_lang_id=None): + super().__init__(args) + self.tgt_dict = tgt_dict + self.data_cfg = S2SDataConfig(Path(args.data) / args.config_yaml) + self.multitask_tasks = {} + if getattr(args, "multitask_config_yaml", None) is not None: + multitask_cfg = MultitaskConfig( + Path(args.data) / args.multitask_config_yaml + ) + for task_name, task_config in multitask_cfg.get_all_tasks().items(): + self.multitask_tasks[task_name] = DummyMultiTask( + task_config, task_config.tgt_dict + ) + self._infer_tgt_lang_id = infer_tgt_lang_id + + @classmethod + def setup_task(cls, args, **kwargs): + data_cfg = data_cfg = S2SDataConfig(Path(args.data) / args.config_yaml) + tgt_dict = None + infer_tgt_lang_id = None + if args.target_is_code: + if data_cfg.prepend_tgt_lang_tag_as_bos: + # dictionary with language tags + dict_path = Path(args.data) / data_cfg.vocab_filename + if not dict_path.is_file(): + raise FileNotFoundError( + f"Dict has to be provided when setting prepend_tgt_lang_tag_as_bos: true, but dict not found: {dict_path}" + ) + tgt_dict = Dictionary.load(dict_path.as_posix()) + + # target langauge for inference + if args.infer_target_lang != "": + tgt_lang_tag = SpeechToTextDataset.LANG_TAG_TEMPLATE.format( + args.infer_target_lang + ) + infer_tgt_lang_id = tgt_dict.index(tgt_lang_tag) + assert infer_tgt_lang_id != tgt_dict.unk() + else: + assert args.target_code_size is not None + + tgt_dict = Dictionary() + for i in range(args.target_code_size): + tgt_dict.add_symbol(str(i)) + logger.info(f"dictionary size: " f"{len(tgt_dict):,}") + + if getattr(args, "train_subset", None) is not None: + if not all(s.startswith("train") for s in args.train_subset.split(",")): + raise ValueError('Train splits should be named like "train*".') + + assert args.n_frames_per_step >= 1 + assert ( + not args.eval_inference + or (args.target_is_code and args.vocoder == "code_hifigan") + or (not args.target_is_code and args.vocoder != "code_hifigan") + ) + + return cls(args, tgt_dict, infer_tgt_lang_id=infer_tgt_lang_id) + + def build_criterion(self, args): + from fairseq import criterions + + if len(self.multitask_tasks) > 0: + if self.args.target_is_code and args._name != "speech_to_unit": + raise ValueError( + "set --criterion speech_to_unit for speech-to-unit loss with multitask" + ) + elif not self.args.target_is_code and args._name != "speech_to_spectrogram": + raise ValueError( + "set --criterion speech_to_spectrogram for speech-to-spectrogram loss with multitask" + ) + + return criterions.build_criterion(args, self) + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + self.datasets[split] = SpeechToSpeechDatasetCreator.from_tsv( + self.args.data, + self.data_cfg, + split, + is_train_split=split.startswith("train"), + epoch=epoch, + seed=self.args.seed, + target_is_code=self.args.target_is_code, + target_dictionary=self.target_dictionary, + n_frames_per_step=self.args.n_frames_per_step, + multitask=self.multitask_tasks, + ) + + @property + def target_dictionary(self): + return self.tgt_dict + + @property + def source_dictionary(self): + return None + + def max_positions(self): + return self.args.max_source_positions, self.args.max_target_positions + + def build_model(self, args, from_checkpoint=False): + args.input_feat_per_channel = self.data_cfg.input_feat_per_channel + args.input_channels = self.data_cfg.input_transformed_channels + args.target_speaker_embed = self.data_cfg.target_speaker_embed is not None + args.n_frames_per_step = self.args.n_frames_per_step + + model = super().build_model(args, from_checkpoint) + + if len(self.multitask_tasks) > 0: + from fairseq.models.speech_to_speech.s2s_transformer import ( + S2STransformerMultitaskModelBase, + ) + + assert isinstance(model, S2STransformerMultitaskModelBase) + + if self.args.eval_inference: + self.eval_gen_args = json.loads(self.args.eval_args) + self.generator = self.build_generator( + [model], Namespace(**self.eval_gen_args) + ) + + return model + + def build_generator( + self, + models, + args, + seq_gen_cls=None, + extra_gen_cls_kwargs=None, + ): + + if not self.args.target_is_code or self.args.eval_inference: + from fairseq.models.text_to_speech.vocoder import get_vocoder + + self.vocoder = get_vocoder(self.args, self.data_cfg) + self.vocoder = ( + self.vocoder.cuda() + if torch.cuda.is_available() and not self.args.cpu + else self.vocoder.cpu() + ) + + if self.args.target_is_code: + if self.args.n_frames_per_step == 1: + seq_generator = super().build_generator( + models, + args, + seq_gen_cls=None, + extra_gen_cls_kwargs=extra_gen_cls_kwargs, + ) + else: + assert ( + getattr(args, "beam", 1) == 1 and getattr(args, "nbest", 1) == 1 + ), "only support viterbi search for stacked units" + seq_generator = StackUnitSequenceGenerator( + self.tgt_dict, + self.args.target_code_size, + ) + else: + if getattr(args, "teacher_forcing", False): + from fairseq.speech_generator import ( + TeacherForcingAutoRegressiveSpeechGenerator, + ) + + generator = TeacherForcingAutoRegressiveSpeechGenerator + logger.info("Teacher forcing mode for generation") + else: + from fairseq.speech_generator import AutoRegressiveSpeechGenerator + + generator = AutoRegressiveSpeechGenerator + seq_generator = generator( + models[0], + self.vocoder, + self.data_cfg, + max_iter=self.args.max_target_positions, + eos_prob_threshold=self.args.eos_prob_threshold, + ) + + return seq_generator + + def train_step( + self, sample, model, criterion, optimizer, update_num, ignore_grad=False + ): + for task_name, task_obj in self.multitask_tasks.items(): + criterion.set_multitask_loss_weight( + task_name, task_obj.args.get_loss_weight(update_num) + ) + + loss, sample_size, logging_output = super().train_step( + sample, model, criterion, optimizer, update_num, ignore_grad + ) + return loss, sample_size, logging_output + + def valid_step(self, sample, model, criterion): + loss, sample_size, logging_output = super().valid_step(sample, model, criterion) + + if self.args.eval_inference: + hypos, inference_losses = self.valid_step_with_inference( + sample, model, self.generator + ) + for k, v in inference_losses.items(): + assert k not in logging_output + logging_output[k] = v + + return loss, sample_size, logging_output + + def valid_step_with_inference(self, sample, model, generator): + if self.args.target_is_code: + hypos = generator.generate([model], sample) + tgt_lens = ( + sample["target_lengths"] - 1 + ) * self.args.n_frames_per_step # strip + for b, (f, l) in enumerate(zip(sample["target"], tgt_lens)): + hypos[b][0]["targ_waveform"] = self.vocoder( + {"code": f[:l] - 4}, # remove , , , + dur_prediction=self.eval_gen_args.get("dur_prediction", False), + ) + if len(hypos[b][0]["tokens"]) > 0: + hypos[b][0]["waveform"] = self.vocoder( + {"code": hypos[b][0]["tokens"] - 4}, + dur_prediction=self.eval_gen_args.get("dur_prediction", False), + ) + else: + hypos[b][0]["waveform"] = torch.flip( + hypos[b][0]["targ_waveform"], dims=[0] + ) + else: + hypos = [ + [hypo] for hypo in generator.generate(model, sample, has_targ=True) + ] + + losses = { + "mcd_loss": 0.0, + "targ_frames": 0.0, + "pred_frames": 0.0, + "path_frames": 0.0, + "nins": 0.0, + "ndel": 0.0, + } + rets = batch_mel_cepstral_distortion( + [hypo[0]["targ_waveform"] for hypo in hypos], + [hypo[0]["waveform"] for hypo in hypos], + self.data_cfg.output_sample_rate, + normalize_type=None, + ) + for d, extra in rets: + pathmap = extra[-1] + losses["mcd_loss"] += d.item() + losses["targ_frames"] += pathmap.size(0) + losses["pred_frames"] += pathmap.size(1) + losses["path_frames"] += pathmap.sum().item() + losses["nins"] += (pathmap.sum(dim=1) - 1).sum().item() + losses["ndel"] += (pathmap.sum(dim=0) - 1).sum().item() + losses["norm_frames"] = losses[ + f"{getattr(self.args, 'mcd_normalize_type', 'targ')}_frames" + ] + + return hypos, losses + + def inference_step( + self, generator, models, sample, prefix_tokens=None, constraints=None + ): + with torch.no_grad(): + if self._infer_tgt_lang_id is not None: + return generator.generate( + models, + sample, + prefix_tokens=prefix_tokens, + constraints=constraints, + bos_token=self._infer_tgt_lang_id, + ) + else: + return super().inference_step( + generator, + models, + sample, + prefix_tokens=prefix_tokens, + constraints=constraints, + ) + + +class DummyMultiTask(LegacyFairseqTask): + def __init__(self, args, tgt_dict): + super().__init__(args) + self.tgt_dict = tgt_dict + + @property + def target_dictionary(self): + return self.tgt_dict + + def inference_step( + self, generator, models, sample, prefix_tokens=None, constraints=None + ): + if self.args.decoder_type == "ctc": + model = models[0] # only support single model + encoder_out = model(**sample) + if hasattr(model, "get_logits"): + emissions = model.get_logits( + encoder_out + ) # no need to normalize emissions + else: + emissions = model.get_normalized_probs(encoder_out, log_probs=True) + return generator.decode( + emissions.transpose(0, 1).float().cpu().contiguous() + ) + else: + raise NotImplementedError("only ctc decoder is supported at the moment") + + def build_generator( + self, models, args, seq_gen_cls=None, extra_gen_cls_kwargs=None + ): + if self.args.decoder_type == "ctc": + from examples.speech_recognition.w2l_decoder import W2lViterbiDecoder + + return W2lViterbiDecoder(args, self.tgt_dict) + else: + raise NotImplementedError("only ctc decoder is supported at the moment") diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_to_text.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_to_text.py new file mode 100644 index 00000000..5818fbe6 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_to_text.py @@ -0,0 +1,186 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +from pathlib import Path +from argparse import Namespace + +from fairseq.data import Dictionary, encoders +from fairseq.data.audio.speech_to_text_dataset import ( + S2TDataConfig, + SpeechToTextDataset, + SpeechToTextDatasetCreator, + get_features_or_waveform, +) +from fairseq.tasks import LegacyFairseqTask, register_task + + +logger = logging.getLogger(__name__) + + +@register_task("speech_to_text") +class SpeechToTextTask(LegacyFairseqTask): + @classmethod + def add_args(cls, parser): + parser.add_argument("data", help="manifest root path") + parser.add_argument( + "--config-yaml", + type=str, + default="config.yaml", + help="Configuration YAML filename (under manifest root)", + ) + parser.add_argument( + "--max-source-positions", + default=6000, + type=int, + metavar="N", + help="max number of tokens in the source sequence", + ) + parser.add_argument( + "--max-target-positions", + default=1024, + type=int, + metavar="N", + help="max number of tokens in the target sequence", + ) + + def __init__(self, args, tgt_dict): + super().__init__(args) + self.tgt_dict = tgt_dict + self.data_cfg = S2TDataConfig(Path(args.data) / args.config_yaml) + self.speaker_to_id = self._get_speaker_to_id() + if ( + self.data_cfg.prepend_tgt_lang_tag + and self.data_cfg.prepend_bos_and_append_tgt_lang_tag + ): + raise ValueError( + "Please set only one of the two options to avoid adding target token multiple times" + ) + + def _get_speaker_to_id(self): + speaker_to_id = None + speaker_set_filename = self.data_cfg.config.get("speaker_set_filename") + if speaker_set_filename is not None: + speaker_set_path = Path(self.args.data) / speaker_set_filename + with open(speaker_set_path) as f: + speaker_to_id = {r.strip(): i for i, r in enumerate(f)} + return speaker_to_id + + @classmethod + def setup_task(cls, args, **kwargs): + data_cfg = S2TDataConfig(Path(args.data) / args.config_yaml) + dict_path = Path(args.data) / data_cfg.vocab_filename + if not dict_path.is_file(): + raise FileNotFoundError(f"Dict not found: {dict_path.as_posix()}") + tgt_dict = Dictionary.load(dict_path.as_posix()) + logger.info( + f"dictionary size ({data_cfg.vocab_filename}): " f"{len(tgt_dict):,}" + ) + + if getattr(args, "train_subset", None) is not None: + if not all(s.startswith("train") for s in args.train_subset.split(",")): + raise ValueError('Train splits should be named like "train*".') + return cls(args, tgt_dict) + + def build_criterion(self, args): + from fairseq import criterions + + if self.data_cfg.prepend_tgt_lang_tag and args.ignore_prefix_size != 1: + raise ValueError( + 'Please set "--ignore-prefix-size 1" since ' + "target language ID token is prepended as BOS." + ) + return criterions.build_criterion(args, self) + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + is_train_split = split.startswith("train") + pre_tokenizer = self.build_tokenizer(self.args) + bpe_tokenizer = self.build_bpe(self.args) + self.datasets[split] = SpeechToTextDatasetCreator.from_tsv( + self.args.data, + self.data_cfg, + split, + self.tgt_dict, + pre_tokenizer, + bpe_tokenizer, + is_train_split=is_train_split, + epoch=epoch, + seed=self.args.seed, + speaker_to_id=self.speaker_to_id, + ) + + @property + def target_dictionary(self): + return self.tgt_dict + + @property + def source_dictionary(self): + return None + + def max_positions(self): + return self.args.max_source_positions, self.args.max_target_positions + + def build_model(self, args, from_checkpoint=False): + args.input_feat_per_channel = self.data_cfg.input_feat_per_channel + args.input_channels = self.data_cfg.input_channels + args.speaker_to_id = self.speaker_to_id + return super(SpeechToTextTask, self).build_model(args, from_checkpoint) + + def build_generator( + self, + models, + args, + seq_gen_cls=None, + extra_gen_cls_kwargs=None, + ): + if self.data_cfg.prepend_tgt_lang_tag and args.prefix_size != 1: + raise ValueError( + 'Please set "--prefix-size 1" since ' + "target language ID token is prepended as BOS." + ) + lang_token_ids = { + i + for s, i in self.tgt_dict.indices.items() + if SpeechToTextDataset.is_lang_tag(s) + } + + if extra_gen_cls_kwargs is None: + extra_gen_cls_kwargs = {} + extra_gen_cls_kwargs["symbols_to_strip_from_output"] = lang_token_ids + + eos_token = ( + args.eos_token + if "eos_token" in args and args.eos_token is not None + else self.data_cfg.config.get("eos_token", None) + ) + + if self.data_cfg.prepend_bos_and_append_tgt_lang_tag and not eos_token: + raise Warning( + "Please provide --eos_token to replace eos in sequence generator" + ) + + eos_id = self.tgt_dict.index(eos_token) if eos_token else None + extra_gen_cls_kwargs["eos"] = eos_id + + return super().build_generator( + models, args, seq_gen_cls=None, extra_gen_cls_kwargs=extra_gen_cls_kwargs + ) + + def build_tokenizer(self, args): + logger.info(f"pre-tokenizer: {self.data_cfg.pre_tokenizer}") + return encoders.build_tokenizer(Namespace(**self.data_cfg.pre_tokenizer)) + + def build_bpe(self, args): + logger.info(f"tokenizer: {self.data_cfg.bpe_tokenizer}") + return encoders.build_bpe(Namespace(**self.data_cfg.bpe_tokenizer)) + + def get_interactive_tokens_and_lengths(self, lines, encode_fn): + n_frames = [get_features_or_waveform(p).shape[0] for p in lines] + return lines, n_frames + + def build_dataset_for_inference(self, src_tokens, src_lengths, **kwargs): + return SpeechToTextDataset( + "interactive", False, self.data_cfg, src_tokens, src_lengths + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_ulm_task.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_ulm_task.py new file mode 100644 index 00000000..b9d3019d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/speech_ulm_task.py @@ -0,0 +1,224 @@ +# Copyright (c) 2017-present, Facebook, Inc. +# All rights reserved. +# +# This source code is licensed under the license found in the LICENSE file in +# the root directory of this source tree. An additional grant of patent rights +# can be found in the PATENTS file in the same directory. + +import logging +import sys +import torch +from dataclasses import dataclass, field +from typing import List, Optional, Tuple + +from fairseq.data import Dictionary +from fairseq.data.codedataset import ExpressiveCodeDataConfig, CodeDataset +from fairseq.dataclass.configs import FairseqDataclass +from fairseq.tasks import register_task +from fairseq.tasks.fairseq_task import FairseqTask +from omegaconf import MISSING, DictConfig + + +logger = logging.getLogger(__name__) + + +class UnitDictionary(Dictionary): + """ + A fixed-sized Dictionary that operates on integer-valued tokens + wth a trivial (identity) token <-> id mapping. + Special symbols (bos, eos, ...) have ids above n_units. + """ + + def __init__( + self, + *, # begin keyword-only arguments + n_units, + bos="", + pad="", + eos="", + unk="", + extra_special_symbols=None, + clip=False, + ): + self.n_units = n_units + self.bos_word, self.unk_word, self.pad_word, self.eos_word = bos, unk, pad, eos + self.clip = clip + + self.symbols = [] + self.count = [] + self.indices = {} + for i in range(n_units): + self.add_symbol(str(i)) + + self.bos_index = self.add_symbol(bos) + self.pad_index = self.add_symbol(pad) + self.eos_index = self.add_symbol(eos) + self.unk_index = self.add_symbol(unk) + + if extra_special_symbols: + for s in extra_special_symbols: + self.add_symbol(s) + self.nspecial = len(self.symbols) + + def encode_line(self, line, append_eos=True, prepend_bos=False) -> torch.IntTensor: + words = [int(x) for x in line.split()] + if self.clip: + words = [min(self.n_units - 1, word) for word in words] + if prepend_bos: + words = [self.bos_index] + words + if append_eos: + words.append(self.eos_index) + ids = torch.IntTensor(words) + return ids + + +@dataclass +class SpeechUnitModelingConfig(FairseqDataclass): + data: str = field(default=MISSING, metadata={"help": "Path to data config.json"}) + max_token_duration: int = field( + default=20, metadata={"help": "all token durations are capped to this value"} + ) + tokens_per_sample: int = field( + default=1024, metadata={"help": "tokens in a sample"} + ) + max_target_positions: int = field( + default=1024, metadata={"help": "max target positions"} + ) + + # duration modeling + ignore_duration_input: bool = field( + default=False, metadata={"help": "whether token durations should be zeroed out"} + ) + discrete_duration: bool = field( + default=False, metadata={"help": "treat duration as discrete variable"} + ) + # F0 modeling + ignore_f0_input: bool = field( + default=False, metadata={"help": "whether F0 should be zeroed out"} + ) + discrete_f0: bool = field( + default=False, metadata={"help": "load quantized f0. get bin from config"} + ) + log_f0: bool = field( + default=False, metadata={"help": "whether f0 should be modeled in log space"} + ) + normalize_f0_mean: bool = field( + default=False, metadata={"help": "whether normalize f0 by speaker mean"} + ) + normalize_f0_std: bool = field( + default=False, metadata={"help": "whether normalize f0 by speaker stddev"} + ) + interpolate_f0: bool = field( + default=False, + metadata={"help": "whether interpolate f0 for non-voiced segments"}, + ) + + # input/output streams + stream_shifts: str = field( + default="0,0", + metadata={ + "help": ( + "comma-separated integer list denoting right-shift for " + "duration and pitch streams" + ) + }, + ) + + +@register_task("speech_unit_modeling", dataclass=SpeechUnitModelingConfig) +class SpeechUnitLanguageModelingTask(FairseqTask): + def __init__(self, cfg: SpeechUnitModelingConfig) -> None: + super().__init__(cfg) + assert not self.cfg.normalize_f0_std or self.cfg.normalize_f0_mean + + self.data_config = ExpressiveCodeDataConfig(cfg.data) + self._source_dictionary = self._target_dictionary = UnitDictionary( + n_units=self.data_config.n_units + ) + self._source_duration_dictionary = self._target_duration_dictionary = ( + UnitDictionary(n_units=self.cfg.max_token_duration + 1, clip=True) + if self.cfg.discrete_duration + else None + ) + self._source_f0_dictionary = self._target_f0_dictionary = ( + UnitDictionary(n_units=self.data_config.f0_vq_n_units) + if self.cfg.discrete_f0 + else None + ) + + self._channel_names = ["token", "duration", "f0"] + self._channel_sizes = [ + len(self.target_dictionary), + len(self.target_duration_dictionary) if self.cfg.discrete_duration else 1, + len(self.target_f0_dictionary) if self.cfg.discrete_f0 else 1, + ] + + @property + def source_dictionary(self) -> Optional[Dictionary]: + return self._source_dictionary + + @property + def source_duration_dictionary(self) -> Optional[Dictionary]: + return self._source_duration_dictionary + + @property + def source_f0_dictionary(self) -> Optional[Dictionary]: + return self._source_f0_dictionary + + @property + def channel_names(self) -> List[str]: + return self._channel_names + + @property + def channel_sizes(self) -> List[int]: + return self._channel_sizes + + @property + def dictionary(self) -> Optional[Dictionary]: + return self._source_dictionary + + @property + def target_dictionary(self) -> Optional[Dictionary]: + return self._target_dictionary + + @property + def target_duration_dictionary(self) -> Optional[Dictionary]: + return self._target_duration_dictionary + + @property + def target_f0_dictionary(self) -> Optional[Dictionary]: + return self._target_f0_dictionary + + @property + def dictionaries(self) -> List[Dictionary]: + return [self._dictionaries[l] for l in self.cfg.labels] + + @classmethod + def setup_task( + cls, cfg: SpeechUnitModelingConfig, **kwargs + ) -> "SpeechUnitLanguageModelingTask": + return cls(cfg) + + def load_dataset(self, split: str, **kwargs) -> None: + self.datasets[split] = CodeDataset( + manifest=self.data_config.manifests[split], + dictionary=self.source_dictionary, + dur_dictionary=self.source_duration_dictionary, + f0_dictionary=self.source_f0_dictionary, + config=self.data_config, + discrete_dur=self.cfg.discrete_duration, + discrete_f0=self.cfg.discrete_f0, + log_f0=self.cfg.log_f0, + normalize_f0_mean=self.cfg.normalize_f0_mean, + normalize_f0_std=self.cfg.normalize_f0_std, + interpolate_f0=self.cfg.interpolate_f0, + shifts=self.cfg.stream_shifts, + ) + + def max_positions(self) -> Tuple[int, int]: + return (sys.maxsize, sys.maxsize) + + def build_criterion(self, cfg: DictConfig): + import fairseq.criterions + + return fairseq.criterions.build_criterion(cfg, self) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/text_to_speech.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/text_to_speech.py new file mode 100644 index 00000000..82e7e664 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/text_to_speech.py @@ -0,0 +1,501 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +import os.path as op + +import torch +import torch.nn.functional as F +import numpy as np + +from fairseq.data.audio.text_to_speech_dataset import TextToSpeechDatasetCreator +from fairseq.tasks import register_task +from fairseq.tasks.speech_to_text import SpeechToTextTask +from fairseq.speech_generator import ( + AutoRegressiveSpeechGenerator, + NonAutoregressiveSpeechGenerator, + TeacherForcingAutoRegressiveSpeechGenerator, +) + +logging.basicConfig( + format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + level=logging.INFO, +) +logger = logging.getLogger(__name__) + + +try: + from tensorboardX import SummaryWriter +except ImportError: + logger.info("Please install tensorboardX: pip install tensorboardX") + SummaryWriter = None + + +@register_task("text_to_speech") +class TextToSpeechTask(SpeechToTextTask): + @staticmethod + def add_args(parser): + parser.add_argument("data", help="manifest root path") + parser.add_argument( + "--config-yaml", + type=str, + default="config.yaml", + help="Configuration YAML filename (under manifest root)", + ) + parser.add_argument( + "--max-source-positions", + default=1024, + type=int, + metavar="N", + help="max number of tokens in the source sequence", + ) + parser.add_argument( + "--max-target-positions", + default=1200, + type=int, + metavar="N", + help="max number of tokens in the target sequence", + ) + parser.add_argument("--n-frames-per-step", type=int, default=1) + parser.add_argument("--eos-prob-threshold", type=float, default=0.5) + parser.add_argument("--eval-inference", action="store_true") + parser.add_argument("--eval-tb-nsample", type=int, default=8) + parser.add_argument("--vocoder", type=str, default="griffin_lim") + parser.add_argument("--spec-bwd-max-iter", type=int, default=8) + + def __init__(self, args, src_dict): + super().__init__(args, src_dict) + self.src_dict = src_dict + self.sr = self.data_cfg.config.get("features").get("sample_rate") + + self.tensorboard_writer = None + self.tensorboard_dir = "" + if args.tensorboard_logdir and SummaryWriter is not None: + self.tensorboard_dir = os.path.join(args.tensorboard_logdir, "valid_extra") + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + is_train_split = split.startswith("train") + pre_tokenizer = self.build_tokenizer(self.args) + bpe_tokenizer = self.build_bpe(self.args) + self.datasets[split] = TextToSpeechDatasetCreator.from_tsv( + self.args.data, + self.data_cfg, + split, + self.src_dict, + pre_tokenizer, + bpe_tokenizer, + is_train_split=is_train_split, + epoch=epoch, + seed=self.args.seed, + n_frames_per_step=self.args.n_frames_per_step, + speaker_to_id=self.speaker_to_id, + ) + + @property + def target_dictionary(self): + return None + + @property + def source_dictionary(self): + return self.src_dict + + def get_speaker_embeddings_path(self): + speaker_emb_path = None + if self.data_cfg.config.get("speaker_emb_filename") is not None: + speaker_emb_path = op.join( + self.args.data, self.data_cfg.config.get("speaker_emb_filename") + ) + return speaker_emb_path + + @classmethod + def get_speaker_embeddings(cls, args): + embed_speaker = None + if args.speaker_to_id is not None: + if args.speaker_emb_path is None: + embed_speaker = torch.nn.Embedding( + len(args.speaker_to_id), args.speaker_embed_dim + ) + else: + speaker_emb_mat = np.load(args.speaker_emb_path) + assert speaker_emb_mat.shape[1] == args.speaker_embed_dim + embed_speaker = torch.nn.Embedding.from_pretrained( + torch.from_numpy(speaker_emb_mat), + freeze=True, + ) + logger.info( + f"load speaker embeddings from {args.speaker_emb_path}. " + f"train embedding? {embed_speaker.weight.requires_grad}\n" + f"embeddings:\n{speaker_emb_mat}" + ) + return embed_speaker + + def build_model(self, cfg, from_checkpoint=False): + cfg.pitch_min = self.data_cfg.config["features"].get("pitch_min", None) + cfg.pitch_max = self.data_cfg.config["features"].get("pitch_max", None) + cfg.energy_min = self.data_cfg.config["features"].get("energy_min", None) + cfg.energy_max = self.data_cfg.config["features"].get("energy_max", None) + cfg.speaker_emb_path = self.get_speaker_embeddings_path() + model = super().build_model(cfg, from_checkpoint) + self.generator = None + if getattr(cfg, "eval_inference", False): + self.generator = self.build_generator([model], cfg) + return model + + def build_generator(self, models, cfg, vocoder=None, **unused): + if vocoder is None: + vocoder = self.build_default_vocoder() + model = models[0] + if getattr(model, "NON_AUTOREGRESSIVE", False): + return NonAutoregressiveSpeechGenerator(model, vocoder, self.data_cfg) + else: + generator = AutoRegressiveSpeechGenerator + if getattr(cfg, "teacher_forcing", False): + generator = TeacherForcingAutoRegressiveSpeechGenerator + logger.info("Teacher forcing mode for generation") + return generator( + model, + vocoder, + self.data_cfg, + max_iter=self.args.max_target_positions, + eos_prob_threshold=self.args.eos_prob_threshold, + ) + + def build_default_vocoder(self): + from fairseq.models.text_to_speech.vocoder import get_vocoder + + vocoder = get_vocoder(self.args, self.data_cfg) + if torch.cuda.is_available() and not self.args.cpu: + vocoder = vocoder.cuda() + else: + vocoder = vocoder.cpu() + return vocoder + + def valid_step(self, sample, model, criterion): + loss, sample_size, logging_output = super().valid_step(sample, model, criterion) + + if getattr(self.args, "eval_inference", False): + hypos, inference_losses = self.valid_step_with_inference( + sample, model, self.generator + ) + for k, v in inference_losses.items(): + assert k not in logging_output + logging_output[k] = v + + picked_id = 0 + if self.tensorboard_dir and (sample["id"] == picked_id).any(): + self.log_tensorboard( + sample, + hypos[: self.args.eval_tb_nsample], + model._num_updates, + is_na_model=getattr(model, "NON_AUTOREGRESSIVE", False), + ) + return loss, sample_size, logging_output + + def valid_step_with_inference(self, sample, model, generator): + hypos = generator.generate(model, sample, has_targ=True) + + losses = { + "mcd_loss": 0.0, + "targ_frames": 0.0, + "pred_frames": 0.0, + "nins": 0.0, + "ndel": 0.0, + } + rets = batch_mel_cepstral_distortion( + [hypo["targ_waveform"] for hypo in hypos], + [hypo["waveform"] for hypo in hypos], + self.sr, + normalize_type=None, + ) + for d, extra in rets: + pathmap = extra[-1] + losses["mcd_loss"] += d.item() + losses["targ_frames"] += pathmap.size(0) + losses["pred_frames"] += pathmap.size(1) + losses["nins"] += (pathmap.sum(dim=1) - 1).sum().item() + losses["ndel"] += (pathmap.sum(dim=0) - 1).sum().item() + + return hypos, losses + + def log_tensorboard(self, sample, hypos, num_updates, is_na_model=False): + if self.tensorboard_writer is None: + self.tensorboard_writer = SummaryWriter(self.tensorboard_dir) + tb_writer = self.tensorboard_writer + for b in range(len(hypos)): + idx = sample["id"][b] + text = sample["src_texts"][b] + targ = hypos[b]["targ_feature"] + pred = hypos[b]["feature"] + attn = hypos[b]["attn"] + + if is_na_model: + data = plot_tts_output( + [targ.transpose(0, 1), pred.transpose(0, 1)], + [f"target (idx={idx})", "output"], + attn, + "alignment", + ret_np=True, + suptitle=text, + ) + else: + eos_prob = hypos[b]["eos_prob"] + data = plot_tts_output( + [targ.transpose(0, 1), pred.transpose(0, 1), attn], + [f"target (idx={idx})", "output", "alignment"], + eos_prob, + "eos prob", + ret_np=True, + suptitle=text, + ) + + tb_writer.add_image( + f"inference_sample_{b}", data, num_updates, dataformats="HWC" + ) + + if hypos[b]["waveform"] is not None: + targ_wave = hypos[b]["targ_waveform"].detach().cpu().float() + pred_wave = hypos[b]["waveform"].detach().cpu().float() + tb_writer.add_audio( + f"inference_targ_{b}", targ_wave, num_updates, sample_rate=self.sr + ) + tb_writer.add_audio( + f"inference_pred_{b}", pred_wave, num_updates, sample_rate=self.sr + ) + + +def save_figure_to_numpy(fig): + data = np.fromstring(fig.canvas.tostring_rgb(), dtype=np.uint8, sep="") + data = data.reshape(fig.canvas.get_width_height()[::-1] + (3,)) + return data + + +DEFAULT_V_MIN = np.log(1e-5) + + +def plot_tts_output( + data_2d, + title_2d, + data_1d, + title_1d, + figsize=(24, 4), + v_min=DEFAULT_V_MIN, + v_max=3, + ret_np=False, + suptitle="", +): + try: + import matplotlib.pyplot as plt + from mpl_toolkits.axes_grid1 import make_axes_locatable + except ImportError: + raise ImportError("Please install Matplotlib: pip install matplotlib") + + data_2d = [ + x.detach().cpu().float().numpy() if isinstance(x, torch.Tensor) else x + for x in data_2d + ] + fig, axes = plt.subplots(1, len(data_2d) + 1, figsize=figsize) + if suptitle: + fig.suptitle(suptitle[:400]) # capped at 400 chars + axes = [axes] if len(data_2d) == 0 else axes + for ax, x, name in zip(axes, data_2d, title_2d): + ax.set_title(name) + divider = make_axes_locatable(ax) + cax = divider.append_axes("right", size="5%", pad=0.05) + im = ax.imshow( + x, + origin="lower", + aspect="auto", + vmin=max(x.min(), v_min), + vmax=min(x.max(), v_max), + ) + fig.colorbar(im, cax=cax, orientation="vertical") + + if isinstance(data_1d, torch.Tensor): + data_1d = data_1d.detach().cpu().numpy() + axes[-1].plot(data_1d) + axes[-1].set_title(title_1d) + plt.tight_layout() + + if ret_np: + fig.canvas.draw() + data = save_figure_to_numpy(fig) + plt.close(fig) + return data + + +def antidiag_indices(offset, min_i=0, max_i=None, min_j=0, max_j=None): + """ + for a (3, 4) matrix with min_i=1, max_i=3, min_j=1, max_j=4, outputs + + offset=2 (1, 1), + offset=3 (2, 1), (1, 2) + offset=4 (2, 2), (1, 3) + offset=5 (2, 3) + + constraints: + i + j = offset + min_j <= j < max_j + min_i <= offset - j < max_i + """ + if max_i is None: + max_i = offset + 1 + if max_j is None: + max_j = offset + 1 + min_j = max(min_j, offset - max_i + 1, 0) + max_j = min(max_j, offset - min_i + 1, offset + 1) + j = torch.arange(min_j, max_j) + i = offset - j + return torch.stack([i, j]) + + +def batch_dynamic_time_warping(distance, shapes=None): + """full batched DTW without any constraints + + distance: (batchsize, max_M, max_N) matrix + shapes: (batchsize,) vector specifying (M, N) for each entry + """ + # ptr: 0=left, 1=up-left, 2=up + ptr2dij = {0: (0, -1), 1: (-1, -1), 2: (-1, 0)} + + bsz, m, n = distance.size() + cumdist = torch.zeros_like(distance) + backptr = torch.zeros_like(distance).type(torch.int32) - 1 + + # initialize + cumdist[:, 0, :] = distance[:, 0, :].cumsum(dim=-1) + cumdist[:, :, 0] = distance[:, :, 0].cumsum(dim=-1) + backptr[:, 0, :] = 0 + backptr[:, :, 0] = 2 + + # DP with optimized anti-diagonal parallelization, O(M+N) steps + for offset in range(2, m + n - 1): + ind = antidiag_indices(offset, 1, m, 1, n) + c = torch.stack( + [ + cumdist[:, ind[0], ind[1] - 1], + cumdist[:, ind[0] - 1, ind[1] - 1], + cumdist[:, ind[0] - 1, ind[1]], + ], + dim=2, + ) + v, b = c.min(axis=-1) + backptr[:, ind[0], ind[1]] = b.int() + cumdist[:, ind[0], ind[1]] = v + distance[:, ind[0], ind[1]] + + # backtrace + pathmap = torch.zeros_like(backptr) + for b in range(bsz): + i = m - 1 if shapes is None else (shapes[b][0] - 1).item() + j = n - 1 if shapes is None else (shapes[b][1] - 1).item() + dtwpath = [(i, j)] + while (i != 0 or j != 0) and len(dtwpath) < 10000: + assert i >= 0 and j >= 0 + di, dj = ptr2dij[backptr[b, i, j].item()] + i, j = i + di, j + dj + dtwpath.append((i, j)) + dtwpath = dtwpath[::-1] + indices = torch.from_numpy(np.array(dtwpath)) + pathmap[b, indices[:, 0], indices[:, 1]] = 1 + + return cumdist, backptr, pathmap + + +def compute_l2_dist(x1, x2): + """compute an (m, n) L2 distance matrix from (m, d) and (n, d) matrices""" + return torch.cdist(x1.unsqueeze(0), x2.unsqueeze(0), p=2).squeeze(0).pow(2) + + +def compute_rms_dist(x1, x2): + l2_dist = compute_l2_dist(x1, x2) + return (l2_dist / x1.size(1)).pow(0.5) + + +def get_divisor(pathmap, normalize_type): + if normalize_type is None: + return 1 + elif normalize_type == "len1": + return pathmap.size(0) + elif normalize_type == "len2": + return pathmap.size(1) + elif normalize_type == "path": + return pathmap.sum().item() + else: + raise ValueError(f"normalize_type {normalize_type} not supported") + + +def batch_compute_distortion(y1, y2, sr, feat_fn, dist_fn, normalize_type): + d, s, x1, x2 = [], [], [], [] + for cur_y1, cur_y2 in zip(y1, y2): + assert cur_y1.ndim == 1 and cur_y2.ndim == 1 + cur_x1 = feat_fn(cur_y1) + cur_x2 = feat_fn(cur_y2) + x1.append(cur_x1) + x2.append(cur_x2) + + cur_d = dist_fn(cur_x1, cur_x2) + d.append(cur_d) + s.append(d[-1].size()) + max_m = max(ss[0] for ss in s) + max_n = max(ss[1] for ss in s) + d = torch.stack( + [F.pad(dd, (0, max_n - dd.size(1), 0, max_m - dd.size(0))) for dd in d] + ) + s = torch.LongTensor(s).to(d.device) + cumdists, backptrs, pathmaps = batch_dynamic_time_warping(d, s) + + rets = [] + itr = zip(s, x1, x2, d, cumdists, backptrs, pathmaps) + for (m, n), cur_x1, cur_x2, dist, cumdist, backptr, pathmap in itr: + cumdist = cumdist[:m, :n] + backptr = backptr[:m, :n] + pathmap = pathmap[:m, :n] + divisor = get_divisor(pathmap, normalize_type) + + distortion = cumdist[-1, -1] / divisor + ret = distortion, (cur_x1, cur_x2, dist, cumdist, backptr, pathmap) + rets.append(ret) + return rets + + +def batch_mel_cepstral_distortion(y1, y2, sr, normalize_type="path", mfcc_fn=None): + """ + https://arxiv.org/pdf/2011.03568.pdf + + The root mean squared error computed on 13-dimensional MFCC using DTW for + alignment. MFCC features are computed from an 80-channel log-mel + spectrogram using a 50ms Hann window and hop of 12.5ms. + + y1: list of waveforms + y2: list of waveforms + sr: sampling rate + """ + + try: + import torchaudio + except ImportError: + raise ImportError("Please install torchaudio: pip install torchaudio") + + if mfcc_fn is None or mfcc_fn.sample_rate != sr: + melkwargs = { + "n_fft": int(0.05 * sr), + "win_length": int(0.05 * sr), + "hop_length": int(0.0125 * sr), + "f_min": 20, + "n_mels": 80, + "window_fn": torch.hann_window, + } + mfcc_fn = torchaudio.transforms.MFCC( + sr, n_mfcc=13, log_mels=True, melkwargs=melkwargs + ).to(y1[0].device) + return batch_compute_distortion( + y1, + y2, + sr, + lambda y: mfcc_fn(y).transpose(-1, -2), + compute_rms_dist, + normalize_type, + ) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/translation.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation.py new file mode 100644 index 00000000..73b3d7c7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation.py @@ -0,0 +1,497 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +import itertools +import json +import logging +import os +from typing import Optional +from argparse import Namespace +from omegaconf import II + +import numpy as np +from fairseq import metrics, utils +from fairseq.data import ( + AppendTokenDataset, + ConcatDataset, + LanguagePairDataset, + PrependTokenDataset, + StripTokenDataset, + TruncateDataset, + data_utils, + encoders, + indexed_dataset, +) +from fairseq.data.indexed_dataset import get_available_dataset_impl +from fairseq.dataclass import ChoiceEnum, FairseqDataclass +from fairseq.tasks import FairseqTask, register_task + + +EVAL_BLEU_ORDER = 4 + + +logger = logging.getLogger(__name__) + + +def load_langpair_dataset( + data_path, + split, + src, + src_dict, + tgt, + tgt_dict, + combine, + dataset_impl, + upsample_primary, + left_pad_source, + left_pad_target, + max_source_positions, + max_target_positions, + prepend_bos=False, + load_alignments=False, + truncate_source=False, + append_source_id=False, + num_buckets=0, + shuffle=True, + pad_to_multiple=1, + prepend_bos_src=None, +): + def split_exists(split, src, tgt, lang, data_path): + filename = os.path.join(data_path, "{}.{}-{}.{}".format(split, src, tgt, lang)) + return indexed_dataset.dataset_exists(filename, impl=dataset_impl) + + src_datasets = [] + tgt_datasets = [] + + for k in itertools.count(): + split_k = split + (str(k) if k > 0 else "") + + # infer langcode + if split_exists(split_k, src, tgt, src, data_path): + prefix = os.path.join(data_path, "{}.{}-{}.".format(split_k, src, tgt)) + elif split_exists(split_k, tgt, src, src, data_path): + prefix = os.path.join(data_path, "{}.{}-{}.".format(split_k, tgt, src)) + else: + if k > 0: + break + else: + raise FileNotFoundError( + "Dataset not found: {} ({})".format(split, data_path) + ) + + src_dataset = data_utils.load_indexed_dataset( + prefix + src, src_dict, dataset_impl + ) + if truncate_source: + src_dataset = AppendTokenDataset( + TruncateDataset( + StripTokenDataset(src_dataset, src_dict.eos()), + max_source_positions - 1, + ), + src_dict.eos(), + ) + src_datasets.append(src_dataset) + + tgt_dataset = data_utils.load_indexed_dataset( + prefix + tgt, tgt_dict, dataset_impl + ) + if tgt_dataset is not None: + tgt_datasets.append(tgt_dataset) + + logger.info( + "{} {} {}-{} {} examples".format( + data_path, split_k, src, tgt, len(src_datasets[-1]) + ) + ) + + if not combine: + break + + assert len(src_datasets) == len(tgt_datasets) or len(tgt_datasets) == 0 + + if len(src_datasets) == 1: + src_dataset = src_datasets[0] + tgt_dataset = tgt_datasets[0] if len(tgt_datasets) > 0 else None + else: + sample_ratios = [1] * len(src_datasets) + sample_ratios[0] = upsample_primary + src_dataset = ConcatDataset(src_datasets, sample_ratios) + if len(tgt_datasets) > 0: + tgt_dataset = ConcatDataset(tgt_datasets, sample_ratios) + else: + tgt_dataset = None + + if prepend_bos: + assert hasattr(src_dict, "bos_index") and hasattr(tgt_dict, "bos_index") + src_dataset = PrependTokenDataset(src_dataset, src_dict.bos()) + if tgt_dataset is not None: + tgt_dataset = PrependTokenDataset(tgt_dataset, tgt_dict.bos()) + elif prepend_bos_src is not None: + logger.info(f"prepending src bos: {prepend_bos_src}") + src_dataset = PrependTokenDataset(src_dataset, prepend_bos_src) + + eos = None + if append_source_id: + src_dataset = AppendTokenDataset( + src_dataset, src_dict.index("[{}]".format(src)) + ) + if tgt_dataset is not None: + tgt_dataset = AppendTokenDataset( + tgt_dataset, tgt_dict.index("[{}]".format(tgt)) + ) + eos = tgt_dict.index("[{}]".format(tgt)) + + align_dataset = None + if load_alignments: + align_path = os.path.join(data_path, "{}.align.{}-{}".format(split, src, tgt)) + if indexed_dataset.dataset_exists(align_path, impl=dataset_impl): + align_dataset = data_utils.load_indexed_dataset( + align_path, None, dataset_impl + ) + + tgt_dataset_sizes = tgt_dataset.sizes if tgt_dataset is not None else None + return LanguagePairDataset( + src_dataset, + src_dataset.sizes, + src_dict, + tgt_dataset, + tgt_dataset_sizes, + tgt_dict, + left_pad_source=left_pad_source, + left_pad_target=left_pad_target, + align_dataset=align_dataset, + eos=eos, + num_buckets=num_buckets, + shuffle=shuffle, + pad_to_multiple=pad_to_multiple, + ) + + +@dataclass +class TranslationConfig(FairseqDataclass): + data: Optional[str] = field( + default=None, + metadata={ + "help": "colon separated path to data directories list, will be iterated upon during epochs " + "in round-robin manner; however, valid and test data are always in the first directory " + "to avoid the need for repeating them in all directories" + }, + ) + source_lang: Optional[str] = field( + default=None, + metadata={ + "help": "source language", + "argparse_alias": "-s", + }, + ) + target_lang: Optional[str] = field( + default=None, + metadata={ + "help": "target language", + "argparse_alias": "-t", + }, + ) + load_alignments: bool = field( + default=False, metadata={"help": "load the binarized alignments"} + ) + left_pad_source: bool = field( + default=True, metadata={"help": "pad the source on the left"} + ) + left_pad_target: bool = field( + default=False, metadata={"help": "pad the target on the left"} + ) + max_source_positions: int = field( + default=1024, metadata={"help": "max number of tokens in the source sequence"} + ) + max_target_positions: int = field( + default=1024, metadata={"help": "max number of tokens in the target sequence"} + ) + upsample_primary: int = field( + default=-1, metadata={"help": "the amount of upsample primary dataset"} + ) + truncate_source: bool = field( + default=False, metadata={"help": "truncate source to max-source-positions"} + ) + num_batch_buckets: int = field( + default=0, + metadata={ + "help": "if >0, then bucket source and target lengths into " + "N buckets and pad accordingly; this is useful on TPUs to minimize the number of compilations" + }, + ) + train_subset: str = II("dataset.train_subset") + dataset_impl: Optional[ChoiceEnum(get_available_dataset_impl())] = II( + "dataset.dataset_impl" + ) + required_seq_len_multiple: int = II("dataset.required_seq_len_multiple") + + # options for reporting BLEU during validation + eval_bleu: bool = field( + default=False, metadata={"help": "evaluation with BLEU scores"} + ) + eval_bleu_args: Optional[str] = field( + default="{}", + metadata={ + "help": 'generation args for BLUE scoring, e.g., \'{"beam": 4, "lenpen": 0.6}\', as JSON string' + }, + ) + eval_bleu_detok: str = field( + default="space", + metadata={ + "help": "detokenize before computing BLEU (e.g., 'moses'); required if using --eval-bleu; " + "use 'space' to disable detokenization; see fairseq.data.encoders for other options" + }, + ) + eval_bleu_detok_args: Optional[str] = field( + default="{}", + metadata={"help": "args for building the tokenizer, if needed, as JSON string"}, + ) + eval_tokenized_bleu: bool = field( + default=False, metadata={"help": "compute tokenized BLEU instead of sacrebleu"} + ) + eval_bleu_remove_bpe: Optional[str] = field( + default=None, + metadata={ + "help": "remove BPE before computing BLEU", + "argparse_const": "@@ ", + }, + ) + eval_bleu_print_samples: bool = field( + default=False, metadata={"help": "print sample generations during validation"} + ) + + +@register_task("translation", dataclass=TranslationConfig) +class TranslationTask(FairseqTask): + """ + Translate from one (source) language to another (target) language. + + Args: + src_dict (~fairseq.data.Dictionary): dictionary for the source language + tgt_dict (~fairseq.data.Dictionary): dictionary for the target language + + .. note:: + + The translation task is compatible with :mod:`fairseq-train`, + :mod:`fairseq-generate` and :mod:`fairseq-interactive`. + """ + + cfg: TranslationConfig + + def __init__(self, cfg: TranslationConfig, src_dict, tgt_dict): + super().__init__(cfg) + self.src_dict = src_dict + self.tgt_dict = tgt_dict + + @classmethod + def setup_task(cls, cfg: TranslationConfig, **kwargs): + """Setup the task (e.g., load dictionaries). + + Args: + args (argparse.Namespace): parsed command-line arguments + """ + + paths = utils.split_paths(cfg.data) + assert len(paths) > 0 + # find language pair automatically + if cfg.source_lang is None or cfg.target_lang is None: + cfg.source_lang, cfg.target_lang = data_utils.infer_language_pair(paths[0]) + if cfg.source_lang is None or cfg.target_lang is None: + raise Exception( + "Could not infer language pair, please provide it explicitly" + ) + + # load dictionaries + src_dict = cls.load_dictionary( + os.path.join(paths[0], "dict.{}.txt".format(cfg.source_lang)) + ) + tgt_dict = cls.load_dictionary( + os.path.join(paths[0], "dict.{}.txt".format(cfg.target_lang)) + ) + assert src_dict.pad() == tgt_dict.pad() + assert src_dict.eos() == tgt_dict.eos() + assert src_dict.unk() == tgt_dict.unk() + logger.info("[{}] dictionary: {} types".format(cfg.source_lang, len(src_dict))) + logger.info("[{}] dictionary: {} types".format(cfg.target_lang, len(tgt_dict))) + + return cls(cfg, src_dict, tgt_dict) + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + paths = utils.split_paths(self.cfg.data) + assert len(paths) > 0 + if split != self.cfg.train_subset: + # if not training data set, use the first shard for valid and test + paths = paths[:1] + data_path = paths[(epoch - 1) % len(paths)] + + # infer langcode + src, tgt = self.cfg.source_lang, self.cfg.target_lang + + self.datasets[split] = load_langpair_dataset( + data_path, + split, + src, + self.src_dict, + tgt, + self.tgt_dict, + combine=combine, + dataset_impl=self.cfg.dataset_impl, + upsample_primary=self.cfg.upsample_primary, + left_pad_source=self.cfg.left_pad_source, + left_pad_target=self.cfg.left_pad_target, + max_source_positions=self.cfg.max_source_positions, + max_target_positions=self.cfg.max_target_positions, + load_alignments=self.cfg.load_alignments, + truncate_source=self.cfg.truncate_source, + num_buckets=self.cfg.num_batch_buckets, + shuffle=(split != "test"), + pad_to_multiple=self.cfg.required_seq_len_multiple, + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, constraints=None): + return LanguagePairDataset( + src_tokens, + src_lengths, + self.source_dictionary, + tgt_dict=self.target_dictionary, + constraints=constraints, + ) + + def build_model(self, cfg, from_checkpoint=False): + model = super().build_model(cfg, from_checkpoint) + if self.cfg.eval_bleu: + detok_args = json.loads(self.cfg.eval_bleu_detok_args) + self.tokenizer = encoders.build_tokenizer( + Namespace(tokenizer=self.cfg.eval_bleu_detok, **detok_args) + ) + + gen_args = json.loads(self.cfg.eval_bleu_args) + self.sequence_generator = self.build_generator( + [model], Namespace(**gen_args) + ) + return model + + def valid_step(self, sample, model, criterion): + loss, sample_size, logging_output = super().valid_step(sample, model, criterion) + if self.cfg.eval_bleu: + bleu = self._inference_with_bleu(self.sequence_generator, sample, model) + logging_output["_bleu_sys_len"] = bleu.sys_len + logging_output["_bleu_ref_len"] = bleu.ref_len + # we split counts into separate entries so that they can be + # summed efficiently across workers using fast-stat-sync + assert len(bleu.counts) == EVAL_BLEU_ORDER + for i in range(EVAL_BLEU_ORDER): + logging_output["_bleu_counts_" + str(i)] = bleu.counts[i] + logging_output["_bleu_totals_" + str(i)] = bleu.totals[i] + return loss, sample_size, logging_output + + def reduce_metrics(self, logging_outputs, criterion): + super().reduce_metrics(logging_outputs, criterion) + if self.cfg.eval_bleu: + + def sum_logs(key): + import torch + + result = sum(log.get(key, 0) for log in logging_outputs) + if torch.is_tensor(result): + result = result.cpu() + return result + + counts, totals = [], [] + for i in range(EVAL_BLEU_ORDER): + counts.append(sum_logs("_bleu_counts_" + str(i))) + totals.append(sum_logs("_bleu_totals_" + str(i))) + + if max(totals) > 0: + # log counts as numpy arrays -- log_scalar will sum them correctly + metrics.log_scalar("_bleu_counts", np.array(counts)) + metrics.log_scalar("_bleu_totals", np.array(totals)) + metrics.log_scalar("_bleu_sys_len", sum_logs("_bleu_sys_len")) + metrics.log_scalar("_bleu_ref_len", sum_logs("_bleu_ref_len")) + + def compute_bleu(meters): + import inspect + + try: + from sacrebleu.metrics import BLEU + + comp_bleu = BLEU.compute_bleu + except ImportError: + # compatibility API for sacrebleu 1.x + import sacrebleu + + comp_bleu = sacrebleu.compute_bleu + + fn_sig = inspect.getfullargspec(comp_bleu)[0] + if "smooth_method" in fn_sig: + smooth = {"smooth_method": "exp"} + else: + smooth = {"smooth": "exp"} + bleu = comp_bleu( + correct=meters["_bleu_counts"].sum, + total=meters["_bleu_totals"].sum, + sys_len=meters["_bleu_sys_len"].sum, + ref_len=meters["_bleu_ref_len"].sum, + **smooth, + ) + return round(bleu.score, 2) + + metrics.log_derived("bleu", compute_bleu) + + def max_positions(self): + """Return the max sentence length allowed by the task.""" + return (self.cfg.max_source_positions, self.cfg.max_target_positions) + + @property + def source_dictionary(self): + """Return the source :class:`~fairseq.data.Dictionary`.""" + return self.src_dict + + @property + def target_dictionary(self): + """Return the target :class:`~fairseq.data.Dictionary`.""" + return self.tgt_dict + + def _inference_with_bleu(self, generator, sample, model): + import sacrebleu + + def decode(toks, escape_unk=False): + s = self.tgt_dict.string( + toks.int().cpu(), + self.cfg.eval_bleu_remove_bpe, + # The default unknown string in fairseq is ``, but + # this is tokenized by sacrebleu as `< unk >`, inflating + # BLEU scores. Instead, we use a somewhat more verbose + # alternative that is unlikely to appear in the real + # reference, but doesn't get split into multiple tokens. + unk_string=("UNKNOWNTOKENINREF" if escape_unk else "UNKNOWNTOKENINHYP"), + ) + if self.tokenizer: + s = self.tokenizer.decode(s) + return s + + gen_out = self.inference_step(generator, [model], sample, prefix_tokens=None) + hyps, refs = [], [] + for i in range(len(gen_out)): + hyps.append(decode(gen_out[i][0]["tokens"])) + refs.append( + decode( + utils.strip_pad(sample["target"][i], self.tgt_dict.pad()), + escape_unk=True, # don't count as matches to the hypo + ) + ) + if self.cfg.eval_bleu_print_samples: + logger.info("example hypothesis: " + hyps[0]) + logger.info("example reference: " + refs[0]) + if self.cfg.eval_tokenized_bleu: + return sacrebleu.corpus_bleu(hyps, [refs], tokenize="none") + else: + return sacrebleu.corpus_bleu(hyps, [refs]) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_from_pretrained_bart.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_from_pretrained_bart.py new file mode 100644 index 00000000..0fd7a5b2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_from_pretrained_bart.py @@ -0,0 +1,132 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import torch +from fairseq import utils +from fairseq.data import LanguagePairDataset + +from . import register_task +from .translation import TranslationTask, load_langpair_dataset + + +@register_task("translation_from_pretrained_bart") +class TranslationFromPretrainedBARTTask(TranslationTask): + """ + Translate from source language to target language with a model initialized with a multilingual pretrain. + + Args: + src_dict (~fairseq.data.Dictionary): dictionary for the source language + tgt_dict (~fairseq.data.Dictionary): dictionary for the target language + + .. note:: + + The translation task is compatible with :mod:`fairseq-train`, + :mod:`fairseq-generate` and :mod:`fairseq-interactive`. + + The translation task provides the following additional command-line + arguments: + + .. argparse:: + :ref: fairseq.tasks.translation_parser + :prog: + """ + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + # fmt: off + TranslationTask.add_args(parser) + parser.add_argument('--langs', type=str, metavar='LANG', + help='comma-separated list of monolingual language, ' + 'for example, "en,de,fr". These should match the ' + 'langs from pretraining (and be in the same order). ' + 'You should always add all pretraining language idx ' + 'during finetuning.') + parser.add_argument('--prepend-bos', action='store_true', + help='prepend bos token to each sentence, which matches ' + 'mBART pretraining') + # fmt: on + + def __init__(self, args, src_dict, tgt_dict): + super().__init__(args, src_dict, tgt_dict) + self.langs = args.langs.split(",") + for d in [src_dict, tgt_dict]: + for l in self.langs: + d.add_symbol("[{}]".format(l)) + d.add_symbol("") + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + paths = utils.split_paths(self.args.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + + # infer langcode + src, tgt = self.args.source_lang, self.args.target_lang + + self.datasets[split] = load_langpair_dataset( + data_path, + split, + src, + self.src_dict, + tgt, + self.tgt_dict, + combine=combine, + dataset_impl=self.args.dataset_impl, + upsample_primary=self.args.upsample_primary, + left_pad_source=self.args.left_pad_source, + left_pad_target=self.args.left_pad_target, + max_source_positions=getattr(self.args, "max_source_positions", 1024), + max_target_positions=getattr(self.args, "max_target_positions", 1024), + load_alignments=self.args.load_alignments, + prepend_bos=getattr(self.args, "prepend_bos", False), + append_source_id=True, + ) + + def build_generator(self, models, args, **unused): + if getattr(args, "score_reference", False): + from fairseq.sequence_scorer import SequenceScorer + + return SequenceScorer( + self.target_dictionary, + eos=self.tgt_dict.index("[{}]".format(self.args.target_lang)), + ) + else: + from fairseq.sequence_generator import SequenceGenerator + + return SequenceGenerator( + models, + self.target_dictionary, + beam_size=getattr(args, "beam", 5), + max_len_a=getattr(args, "max_len_a", 0), + max_len_b=getattr(args, "max_len_b", 200), + min_len=getattr(args, "min_len", 1), + normalize_scores=(not getattr(args, "unnormalized", False)), + len_penalty=getattr(args, "lenpen", 1), + unk_penalty=getattr(args, "unkpen", 0), + temperature=getattr(args, "temperature", 1.0), + match_source_len=getattr(args, "match_source_len", False), + no_repeat_ngram_size=getattr(args, "no_repeat_ngram_size", 0), + eos=self.tgt_dict.index("[{}]".format(self.args.target_lang)), + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, constraints=None): + src_lang_id = self.source_dictionary.index("[{}]".format(self.args.source_lang)) + source_tokens = [] + for s_t in src_tokens: + s_t = torch.cat([s_t, s_t.new(1).fill_(src_lang_id)]) + source_tokens.append(s_t) + dataset = LanguagePairDataset( + source_tokens, + src_lengths, + self.source_dictionary, + tgt_dict=self.target_dictionary, + constraints=constraints, + ) + return dataset diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_from_pretrained_xlm.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_from_pretrained_xlm.py new file mode 100644 index 00000000..a05f2891 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_from_pretrained_xlm.py @@ -0,0 +1,39 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass +from fairseq.data.legacy.masked_lm_dictionary import MaskedLMDictionary +from fairseq.tasks.translation import TranslationConfig, TranslationTask + +from . import register_task + + +@dataclass +class TranslationFromPretrainedXLMConfig(TranslationConfig): + pass + + +@register_task( + "translation_from_pretrained_xlm", dataclass=TranslationFromPretrainedXLMConfig +) +class TranslationFromPretrainedXLMTask(TranslationTask): + """ + Same as TranslationTask except use the MaskedLMDictionary class so that + we can load data that was binarized with the MaskedLMDictionary class. + + This task should be used for the entire training pipeline when we want to + train an NMT model from a pretrained XLM checkpoint: binarizing NMT data, + training NMT with the pretrained XLM checkpoint, and subsequent evaluation + of that trained model. + """ + + @classmethod + def load_dictionary(cls, filename): + """Load the masked LM dictionary from the filename + + Args: + filename (str): the filename + """ + return MaskedLMDictionary.load(filename) diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_lev.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_lev.py new file mode 100644 index 00000000..b45fecd1 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_lev.py @@ -0,0 +1,195 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +from dataclasses import dataclass, field +import torch +from fairseq import utils +from fairseq.data import LanguagePairDataset +from fairseq.dataclass import ChoiceEnum +from fairseq.tasks import register_task +from fairseq.tasks.translation import ( + TranslationConfig, + TranslationTask, + load_langpair_dataset, +) +from fairseq.utils import new_arange + + +NOISE_CHOICES = ChoiceEnum(["random_delete", "random_mask", "no_noise", "full_mask"]) + + +@dataclass +class TranslationLevenshteinConfig(TranslationConfig): + noise: NOISE_CHOICES = field( + default="random_delete", + metadata={"help": "type of noise"}, + ) + + +@register_task("translation_lev", dataclass=TranslationLevenshteinConfig) +class TranslationLevenshteinTask(TranslationTask): + """ + Translation (Sequence Generation) task for Levenshtein Transformer + See `"Levenshtein Transformer" `_. + """ + + cfg: TranslationLevenshteinConfig + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + paths = utils.split_paths(self.cfg.data) + assert len(paths) > 0 + data_path = paths[(epoch - 1) % len(paths)] + + # infer langcode + src, tgt = self.cfg.source_lang, self.cfg.target_lang + + self.datasets[split] = load_langpair_dataset( + data_path, + split, + src, + self.src_dict, + tgt, + self.tgt_dict, + combine=combine, + dataset_impl=self.cfg.dataset_impl, + upsample_primary=self.cfg.upsample_primary, + left_pad_source=self.cfg.left_pad_source, + left_pad_target=self.cfg.left_pad_target, + max_source_positions=self.cfg.max_source_positions, + max_target_positions=self.cfg.max_target_positions, + prepend_bos=True, + ) + + def inject_noise(self, target_tokens): + def _random_delete(target_tokens): + pad = self.tgt_dict.pad() + bos = self.tgt_dict.bos() + eos = self.tgt_dict.eos() + + max_len = target_tokens.size(1) + target_mask = target_tokens.eq(pad) + target_score = target_tokens.clone().float().uniform_() + target_score.masked_fill_( + target_tokens.eq(bos) | target_tokens.eq(eos), 0.0 + ) + target_score.masked_fill_(target_mask, 1) + target_score, target_rank = target_score.sort(1) + target_length = target_mask.size(1) - target_mask.float().sum( + 1, keepdim=True + ) + + # do not delete and (we assign 0 score for them) + target_cutoff = ( + 2 + + ( + (target_length - 2) + * target_score.new_zeros(target_score.size(0), 1).uniform_() + ).long() + ) + target_cutoff = target_score.sort(1)[1] >= target_cutoff + + prev_target_tokens = ( + target_tokens.gather(1, target_rank) + .masked_fill_(target_cutoff, pad) + .gather(1, target_rank.masked_fill_(target_cutoff, max_len).sort(1)[1]) + ) + prev_target_tokens = prev_target_tokens[ + :, : prev_target_tokens.ne(pad).sum(1).max() + ] + + return prev_target_tokens + + def _random_mask(target_tokens): + pad = self.tgt_dict.pad() + bos = self.tgt_dict.bos() + eos = self.tgt_dict.eos() + unk = self.tgt_dict.unk() + + target_masks = ( + target_tokens.ne(pad) & target_tokens.ne(bos) & target_tokens.ne(eos) + ) + target_score = target_tokens.clone().float().uniform_() + target_score.masked_fill_(~target_masks, 2.0) + target_length = target_masks.sum(1).float() + target_length = target_length * target_length.clone().uniform_() + target_length = target_length + 1 # make sure to mask at least one token. + + _, target_rank = target_score.sort(1) + target_cutoff = new_arange(target_rank) < target_length[:, None].long() + prev_target_tokens = target_tokens.masked_fill( + target_cutoff.scatter(1, target_rank, target_cutoff), unk + ) + return prev_target_tokens + + def _full_mask(target_tokens): + pad = self.tgt_dict.pad() + bos = self.tgt_dict.bos() + eos = self.tgt_dict.eos() + unk = self.tgt_dict.unk() + + target_mask = ( + target_tokens.eq(bos) | target_tokens.eq(eos) | target_tokens.eq(pad) + ) + return target_tokens.masked_fill(~target_mask, unk) + + if self.cfg.noise == "random_delete": + return _random_delete(target_tokens) + elif self.cfg.noise == "random_mask": + return _random_mask(target_tokens) + elif self.cfg.noise == "full_mask": + return _full_mask(target_tokens) + elif self.cfg.noise == "no_noise": + return target_tokens + else: + raise NotImplementedError + + def build_generator(self, models, args, **unused): + # add models input to match the API for SequenceGenerator + from fairseq.iterative_refinement_generator import IterativeRefinementGenerator + + return IterativeRefinementGenerator( + self.target_dictionary, + eos_penalty=getattr(args, "iter_decode_eos_penalty", 0.0), + max_iter=getattr(args, "iter_decode_max_iter", 10), + beam_size=getattr(args, "iter_decode_with_beam", 1), + reranking=getattr(args, "iter_decode_with_external_reranker", False), + decoding_format=getattr(args, "decoding_format", None), + adaptive=not getattr(args, "iter_decode_force_max_iter", False), + retain_history=getattr(args, "retain_iter_history", False), + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, constraints=None): + if constraints is not None: + # Though see Susanto et al. (ACL 2020): https://www.aclweb.org/anthology/2020.acl-main.325/ + raise NotImplementedError( + "Constrained decoding with the translation_lev task is not supported" + ) + + return LanguagePairDataset( + src_tokens, src_lengths, self.source_dictionary, append_bos=True + ) + + def train_step( + self, sample, model, criterion, optimizer, update_num, ignore_grad=False + ): + model.train() + sample["prev_target"] = self.inject_noise(sample["target"]) + loss, sample_size, logging_output = criterion(model, sample) + if ignore_grad: + loss *= 0 + optimizer.backward(loss) + return loss, sample_size, logging_output + + def valid_step(self, sample, model, criterion): + model.eval() + with torch.no_grad(): + sample["prev_target"] = self.inject_noise(sample["target"]) + loss, sample_size, logging_output = criterion(model, sample) + return loss, sample_size, logging_output diff --git a/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_multi_simple_epoch.py b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_multi_simple_epoch.py new file mode 100644 index 00000000..5db36a7c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tasks/translation_multi_simple_epoch.py @@ -0,0 +1,441 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import datetime +import logging +import time + +import torch +from fairseq.data import ( + FairseqDataset, + LanguagePairDataset, + ListDataset, + data_utils, + iterators, +) +from fairseq.data.multilingual.multilingual_data_manager import ( + MultilingualDatasetManager, +) +from fairseq.data.multilingual.sampling_method import SamplingMethod +from fairseq.tasks import LegacyFairseqTask, register_task +from fairseq.utils import FileContentsAction + + +### +def get_time_gap(s, e): + return ( + datetime.datetime.fromtimestamp(e) - datetime.datetime.fromtimestamp(s) + ).__str__() + + +### + + +logger = logging.getLogger(__name__) + + +@register_task("translation_multi_simple_epoch") +class TranslationMultiSimpleEpochTask(LegacyFairseqTask): + """ + Translate from one (source) language to another (target) language. + + Args: + langs (List[str]): a list of languages that are being supported + dicts (Dict[str, fairseq.data.Dictionary]): mapping from supported languages to their dictionaries + training (bool): whether the task should be configured for training or not + + .. note:: + + The translation task is compatible with :mod:`fairseq-train`, + :mod:`fairseq-generate` and :mod:`fairseq-interactive`. + + The translation task provides the following additional command-line + arguments: + + .. argparse:: + :ref: fairseq.tasks.translation_parser + :prog: + """ + + @staticmethod + def add_args(parser): + """Add task-specific arguments to the parser.""" + # fmt: off + parser.add_argument('-s', '--source-lang', default=None, metavar='SRC', + help='inference source language') + parser.add_argument('-t', '--target-lang', default=None, metavar='TARGET', + help='inference target language') + parser.add_argument('--lang-pairs', default=None, metavar='PAIRS', + help='comma-separated list of language pairs (in training order): en-de,en-fr,de-fr', + action=FileContentsAction) + parser.add_argument('--keep-inference-langtok', action='store_true', + help='keep language tokens in inference output (e.g. for analysis or debugging)') + + SamplingMethod.add_arguments(parser) + MultilingualDatasetManager.add_args(parser) + # fmt: on + + def __init__(self, args, langs, dicts, training): + super().__init__(args) + self.langs = langs + self.dicts = dicts + self.training = training + if training: + self.lang_pairs = args.lang_pairs + else: + self.lang_pairs = ["{}-{}".format(args.source_lang, args.target_lang)] + # eval_lang_pairs for multilingual translation is usually all of the + # lang_pairs. However for other multitask settings or when we want to + # optimize for certain languages we want to use a different subset. Thus + # the eval_lang_pairs class variable is provided for classes that extend + # this class. + self.eval_lang_pairs = self.lang_pairs + # model_lang_pairs will be used to build encoder-decoder model pairs in + # models.build_model(). This allows multitask type of sub-class can + # build models other than the input lang_pairs + self.model_lang_pairs = self.lang_pairs + self.source_langs = [d.split("-")[0] for d in self.lang_pairs] + self.target_langs = [d.split("-")[1] for d in self.lang_pairs] + self.check_dicts(self.dicts, self.source_langs, self.target_langs) + + self.sampling_method = SamplingMethod.build_sampler(args, self) + self.data_manager = MultilingualDatasetManager.setup_data_manager( + args, self.lang_pairs, langs, dicts, self.sampling_method + ) + + def check_dicts(self, dicts, source_langs, target_langs): + if self.args.source_dict is not None or self.args.target_dict is not None: + # no need to check whether the source side and target side are sharing dictionaries + return + src_dict = dicts[source_langs[0]] + tgt_dict = dicts[target_langs[0]] + for src_lang in source_langs: + assert ( + src_dict == dicts[src_lang] + ), "Diffrent dictionary are specified for different source languages; " + "TranslationMultiSimpleEpochTask only supports one shared dictionary across all source languages" + for tgt_lang in target_langs: + assert ( + tgt_dict == dicts[tgt_lang] + ), "Diffrent dictionary are specified for different target languages; " + "TranslationMultiSimpleEpochTask only supports one shared dictionary across all target languages" + + @classmethod + def setup_task(cls, args, **kwargs): + langs, dicts, training = MultilingualDatasetManager.prepare( + cls.load_dictionary, args, **kwargs + ) + return cls(args, langs, dicts, training) + + def has_sharded_data(self, split): + return self.data_manager.has_sharded_data(split) + + def load_dataset(self, split, epoch=1, combine=False, **kwargs): + """Load a given dataset split. + + Args: + split (str): name of the split (e.g., train, valid, test) + """ + if split in self.datasets: + dataset = self.datasets[split] + if self.has_sharded_data(split): + if self.args.virtual_epoch_size is not None: + if dataset.load_next_shard: + shard_epoch = dataset.shard_epoch + else: + # no need to load next shard so skip loading + # also this avoid always loading from beginning of the data + return + else: + shard_epoch = epoch + else: + # estimate the shard epoch from virtual data size and virtual epoch size + shard_epoch = self.data_manager.estimate_global_pass_epoch(epoch) + logger.info(f"loading data for {split} epoch={epoch}/{shard_epoch}") + logger.info(f"mem usage: {data_utils.get_mem_usage()}") + if split in self.datasets: + del self.datasets[split] + logger.info("old dataset deleted manually") + logger.info(f"mem usage: {data_utils.get_mem_usage()}") + self.datasets[split] = self.data_manager.load_dataset( + split, + self.training, + epoch=epoch, + combine=combine, + shard_epoch=shard_epoch, + **kwargs, + ) + + def build_dataset_for_inference(self, src_tokens, src_lengths, constraints=None): + if constraints is not None: + raise NotImplementedError( + "Constrained decoding with the multilingual_translation task is not supported" + ) + + src_data = ListDataset(src_tokens, src_lengths) + dataset = LanguagePairDataset(src_data, src_lengths, self.source_dictionary) + src_langtok_spec, tgt_langtok_spec = self.args.langtoks["main"] + if self.args.lang_tok_replacing_bos_eos: + dataset = self.data_manager.alter_dataset_langtok( + dataset, + src_eos=self.source_dictionary.eos(), + src_lang=self.args.source_lang, + tgt_eos=self.target_dictionary.eos(), + tgt_lang=self.args.target_lang, + src_langtok_spec=src_langtok_spec, + tgt_langtok_spec=tgt_langtok_spec, + ) + else: + dataset.src = self.data_manager.src_dataset_tranform_func( + self.args.source_lang, + self.args.target_lang, + dataset=dataset.src, + spec=src_langtok_spec, + ) + return dataset + + def build_generator( + self, + models, + args, + seq_gen_cls=None, + extra_gen_cls_kwargs=None, + ): + if not getattr(args, "keep_inference_langtok", False): + _, tgt_langtok_spec = self.args.langtoks["main"] + if tgt_langtok_spec: + tgt_lang_tok = self.data_manager.get_decoder_langtok( + self.args.target_lang, tgt_langtok_spec + ) + extra_gen_cls_kwargs = extra_gen_cls_kwargs or {} + extra_gen_cls_kwargs["symbols_to_strip_from_output"] = {tgt_lang_tok} + + return super().build_generator( + models, args, seq_gen_cls=None, extra_gen_cls_kwargs=extra_gen_cls_kwargs + ) + + def build_model(self, args, from_checkpoint=False): + return super().build_model(args, from_checkpoint) + + def valid_step(self, sample, model, criterion): + loss, sample_size, logging_output = super().valid_step(sample, model, criterion) + return loss, sample_size, logging_output + + def inference_step( + self, generator, models, sample, prefix_tokens=None, constraints=None + ): + with torch.no_grad(): + _, tgt_langtok_spec = self.args.langtoks["main"] + if not self.args.lang_tok_replacing_bos_eos: + if prefix_tokens is None and tgt_langtok_spec: + tgt_lang_tok = self.data_manager.get_decoder_langtok( + self.args.target_lang, tgt_langtok_spec + ) + src_tokens = sample["net_input"]["src_tokens"] + bsz = src_tokens.size(0) + prefix_tokens = ( + torch.LongTensor([[tgt_lang_tok]]).expand(bsz, 1).to(src_tokens) + ) + return generator.generate( + models, + sample, + prefix_tokens=prefix_tokens, + constraints=constraints, + ) + else: + return generator.generate( + models, + sample, + prefix_tokens=prefix_tokens, + bos_token=self.data_manager.get_decoder_langtok( + self.args.target_lang, tgt_langtok_spec + ) + if tgt_langtok_spec + else self.target_dictionary.eos(), + ) + + def reduce_metrics(self, logging_outputs, criterion): + super().reduce_metrics(logging_outputs, criterion) + + def max_positions(self): + """Return the max sentence length allowed by the task.""" + return (self.args.max_source_positions, self.args.max_target_positions) + + @property + def source_dictionary(self): + return self.data_manager.get_source_dictionary(self.source_langs[0]) + + @property + def target_dictionary(self): + return self.data_manager.get_target_dictionary(self.target_langs[0]) + + def create_batch_sampler_func( + self, + max_positions, + ignore_invalid_inputs, + max_tokens, + max_sentences, + required_batch_size_multiple=1, + seed=1, + ): + def construct_batch_sampler(dataset, epoch): + splits = [ + s for s, _ in self.datasets.items() if self.datasets[s] == dataset + ] + split = splits[0] if len(splits) > 0 else None + # NEW implementation + if epoch is not None: + # initialize the dataset with the correct starting epoch + dataset.set_epoch(epoch) + + # get indices ordered by example size + start_time = time.time() + logger.info(f"start batch sampler: mem usage: {data_utils.get_mem_usage()}") + + with data_utils.numpy_seed(seed): + indices = dataset.ordered_indices() + logger.info( + f"[{split}] @batch_sampler order indices time: {get_time_gap(start_time, time.time())}" + ) + logger.info(f"mem usage: {data_utils.get_mem_usage()}") + + # filter examples that are too large + if max_positions is not None: + my_time = time.time() + indices = self.filter_indices_by_size( + indices, dataset, max_positions, ignore_invalid_inputs + ) + logger.info( + f"[{split}] @batch_sampler filter_by_size time: {get_time_gap(my_time, time.time())}" + ) + logger.info(f"mem usage: {data_utils.get_mem_usage()}") + + # create mini-batches with given size constraints + my_time = time.time() + batch_sampler = dataset.batch_by_size( + indices, + max_tokens=max_tokens, + max_sentences=max_sentences, + required_batch_size_multiple=required_batch_size_multiple, + ) + + logger.info( + f"[{split}] @batch_sampler batch_by_size time: {get_time_gap(my_time, time.time())}" + ) + logger.info( + f"[{split}] per epoch batch_sampler set-up time: {get_time_gap(start_time, time.time())}" + ) + logger.info(f"mem usage: {data_utils.get_mem_usage()}") + + return batch_sampler + + return construct_batch_sampler + + # we need to override get_batch_iterator because we want to reset the epoch iterator each time + def get_batch_iterator( + self, + dataset, + max_tokens=None, + max_sentences=None, + max_positions=None, + ignore_invalid_inputs=False, + required_batch_size_multiple=1, + seed=1, + num_shards=1, + shard_id=0, + num_workers=0, + epoch=1, + data_buffer_size=0, + disable_iterator_cache=False, + skip_remainder_batch=False, + grouped_shuffling=False, + update_epoch_batch_itr=False, + ): + """ + Get an iterator that yields batches of data from the given dataset. + + Args: + dataset (~fairseq.data.FairseqDataset): dataset to batch + max_tokens (int, optional): max number of tokens in each batch + (default: None). + max_sentences (int, optional): max number of sentences in each + batch (default: None). + max_positions (optional): max sentence length supported by the + model (default: None). + ignore_invalid_inputs (bool, optional): don't raise Exception for + sentences that are too long (default: False). + required_batch_size_multiple (int, optional): require batch size to + be a multiple of N (default: 1). + seed (int, optional): seed for random number generator for + reproducibility (default: 1). + num_shards (int, optional): shard the data iterator into N + shards (default: 1). + shard_id (int, optional): which shard of the data iterator to + return (default: 0). + num_workers (int, optional): how many subprocesses to use for data + loading. 0 means the data will be loaded in the main process + (default: 0). + epoch (int, optional): the epoch to start the iterator from + (default: 0). + data_buffer_size (int, optional): number of batches to + preload (default: 0). + disable_iterator_cache (bool, optional): don't cache the + EpochBatchIterator (ignores `FairseqTask::can_reuse_epoch_itr`) + (default: False). + grouped_shuffling (bool, optional): group batches with each groups + containing num_shards batches and shuffle groups. Reduces difference + between sequence lengths among workers for batches sorted by length. + update_epoch_batch_itr (bool optional): if true then donot use the cached + batch iterator for the epoch + + Returns: + ~fairseq.iterators.EpochBatchIterator: a batched iterator over the + given dataset split + """ + # initialize the dataset with the correct starting epoch + assert isinstance(dataset, FairseqDataset) + if dataset in self.dataset_to_epoch_iter: + return self.dataset_to_epoch_iter[dataset] + if self.args.sampling_method == "RoundRobin": + batch_iter = super().get_batch_iterator( + dataset, + max_tokens=max_tokens, + max_sentences=max_sentences, + max_positions=max_positions, + ignore_invalid_inputs=ignore_invalid_inputs, + required_batch_size_multiple=required_batch_size_multiple, + seed=seed, + num_shards=num_shards, + shard_id=shard_id, + num_workers=num_workers, + epoch=epoch, + data_buffer_size=data_buffer_size, + disable_iterator_cache=disable_iterator_cache, + skip_remainder_batch=skip_remainder_batch, + update_epoch_batch_itr=update_epoch_batch_itr, + ) + self.dataset_to_epoch_iter[dataset] = batch_iter + return batch_iter + + construct_batch_sampler = self.create_batch_sampler_func( + max_positions, + ignore_invalid_inputs, + max_tokens, + max_sentences, + required_batch_size_multiple=required_batch_size_multiple, + seed=seed, + ) + + epoch_iter = iterators.EpochBatchIterator( + dataset=dataset, + collate_fn=dataset.collater, + batch_sampler=construct_batch_sampler, + seed=seed, + num_shards=num_shards, + shard_id=shard_id, + num_workers=num_workers, + epoch=epoch, + ) + return epoch_iter diff --git a/PyTorch/NLP/new-Transformer/fairseq/token_generation_constraints.py b/PyTorch/NLP/new-Transformer/fairseq/token_generation_constraints.py new file mode 100644 index 00000000..e708dc51 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/token_generation_constraints.py @@ -0,0 +1,506 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +"""Implements tracking of constraints for a beam item. + +A list of constraints is given as a list of one or more token +sequences, each of length at least one token. For example, for an input sentence + +> Die maschinelle Übersetzung ist schwer zu kontrollieren. + +We could have the constraints: +* to influence +* hard + +There are two implementations: +* OrderedConstraintState: Tracks progress through an ordered list of multitoken constraints. +* UnorderedConstraintState: Tracks progress through an unordered list of multitoken constraints. + +The difference is that in the first, the constraints are assumed to be +in order; the algorithm will permit zero or more tokens between them. +In the second, the constraints are not ordered, so many orderings will +be explored. + +The same sequence can be present any number of times, and will appear +that many times in the output. +""" + +from collections import Counter +from typing import List, Optional, Set, Tuple + +import torch + + +class ConstraintState: + def __init__(self): + pass + + +def pack_constraints(batch_constraints: List[List[torch.Tensor]]) -> torch.Tensor: + """Takes a list of list of constraints in tensor form (a list of + tensor constraints for each sentence) and transforms it into a + packed Tensor. For example, here is a batch of size 3 with 3, 0, + and 1 constraints: + + [ [ [3 1 2], [3], [4 5 6 7], ] + [], + [ [1 8 9 10 1 4 11 12], ] + ] + + Its corresponding packed structure is: + + [ [ 3 3 1 2 0 3 0 4 5 6 7 0], + [ 0 0 0 0 0 0 0 0 0 0 0 0], + [ 1 1 8 9 10 1 4 11 12 0 0 0] ] + + The packed tensor has shape (batch size, maxlen), where + maxlen is defined below. Each row contains concatenated + constraint tokens for that sentence, with 0 appended after + each constraint. The first item in each row is the number + of constraints for that sentence. So maxlen is the maximum + of + + (number of constraints) + (sum length of constraints) + 1. + + across all sentences in the batch. + """ + # The maximum word length of concatenated constraints for any sentence + max_constraints_len = 1 + for sentence_constraints in batch_constraints: + if len(sentence_constraints): + # number of constraints, plus sum of constrain lens, plus a zero after each + constraints_len = ( + 1 + + sum([c.size(0) for c in sentence_constraints]) + + len(sentence_constraints) + ) + max_constraints_len = max(max_constraints_len, constraints_len) + + batch_size = len(batch_constraints) + constraints_tensor = torch.zeros((batch_size, max_constraints_len)).long() + for i, sentence_constraints in enumerate(batch_constraints): + constraints_tensor[i, 0] = len(sentence_constraints) + offset = 1 + for j, constraint in enumerate(sentence_constraints): + this_len = constraint.size(0) + constraints_tensor[i, offset : offset + this_len] = constraint + offset += this_len + 1 + + return constraints_tensor.long() + + +def unpack_constraints(constraint_tensor: torch.Tensor) -> List[torch.Tensor]: + """ + Transforms *one row* of a packed constraint tensor (e.g., for one + sentence in the batch) into a list of constraint tensors. + """ + constraint_list = [] + num_constraints = constraint_tensor[0] + constraints = constraint_tensor.tolist() + offset = 1 + for i in range(num_constraints): + where = constraints.index(0, offset) + constraint_list.append(constraint_tensor[offset:where]) + offset = where + 1 + + return constraint_list + + +class ConstraintNode: + """ + Represents a node in a trie managing unordered constraints. + """ + + def __init__(self, token: int = None, parent=None): + # The token associate with this node (None for the root) + self.token = int(token) if token is not None else None + # The parent (None at the root) + self.parent = parent + # Whether this node is a completed constraint + self.terminal = 0 + # List of child nodes + self.children = {} + + # The cumulative number of constraints from this point in the + # trie forward + self.num_constraints = 0 + + @property + def id(self): + return self.token + + def __str__(self): + term = self.terminal != 0 + return f"[{self.token}].{term}#{self.num_constraints}" + + def __getitem__(self, key: int): + return self.children.get(key, None) + + def next_tokens(self) -> Set[int]: + """The set of child labels.""" + return set(self.children.keys()) + + @staticmethod + def create(constraints: List[List[int]]): + root = ConstraintNode() + for sequence in constraints: + root.add_sequence(sequence) + + return root + + @staticmethod + def print_graph(node: "ConstraintNode"): + if len(node.children) == 0: + return str(node) + else: + s = f"({node}" + for child in node.children.values(): + s += " " + ConstraintNode.print_graph(child) + s += ")" + return s + + def token_counts(self) -> Counter: + """Returns a counter of the number of times each token is used + in a constraint. + """ + token_counts = Counter() + kids = list(self.children.values()) + while len(kids) > 0: + kid = kids.pop() + token_counts[kid.id] += kid.num_constraints + kids += list(kid.children.values()) + + return token_counts + + def tokens(self) -> Set[int]: + """Returns the set of tokens in constraints.""" + return set(self.token_counts().keys()) + + def add_sequence(self, sequence: List[int]): + """Adds a constraint, represented as a list of integers, to + the trie.""" + assert len(sequence) > 0 + + token = int(sequence[0]) + if token not in self.children: + self.children[token] = ConstraintNode(token, parent=self) + + node = self.children[token] + if len(sequence) == 1: + node.terminal += 1 + node.num_constraints += 1 + parent = node.parent + while parent is not None: + parent.num_constraints += 1 + parent = parent.parent + else: + node.add_sequence(sequence[1:]) + + +class UnorderedConstraintState(ConstraintState): + """ + Records progress through the set of constraints for each item in the beam + using a trie. + """ + + def __init__(self, node: ConstraintNode, copy_from: "ConstraintState" = None): + self.node = node + + if copy_from is None: + # The root node + self.root = node + # The set of states in the graph that have been completed + self.completed = Counter() + # The... + self.generated = Counter() + # The list of tokens we need to generate + self.needed_tokens = self.root.tokens() + else: + self.completed = Counter(copy_from.completed) + self.generated = Counter(copy_from.generated) + self.root = copy_from.root + + # Mark the node as generated + if self.node != self.root: + self.generated[node] += 1 + + @staticmethod + def create(constraint_tensor: torch.Tensor): + constraint_list = unpack_constraints(constraint_tensor) + constraint_trie_root = ConstraintNode.create(constraint_list) + return UnorderedConstraintState(constraint_trie_root) + + def __str__(self): + gen_str = ",".join([str(node) for node in self.generated]) + return f"{self.name}/{self.bank}({gen_str})x{self.num_completed}" + + def __copy__(self): + copied_state = UnorderedConstraintState(self.node, copy_from=self) + return copied_state + + def copy(self): + return self.__copy__() + + @property + def name(self): + if self.node.id is None: + return "ROOT" + else: + return str(self.node.id) + + @property + def is_root(self): + return self.node == self.root + + @property + def bank(self): + return sum(self.generated.values()) + + @property + def num_completed(self): + """The number of constraints (not constraint tokens) that are completed. + In addition to the already-completed states, we need to account for the + current state, which might get marked as completed when another token + is generated. + """ + in_final = self.node.terminal and self.completed[self.node] < self.node.terminal + return sum(self.completed.values()) + in_final + + @property + def finished(self): + return self.root.num_constraints - self.num_completed == 0 + + @property + def token_counts(self): + return self.root.token_counts() + + @property + def tokens(self): + return self.root.tokens() + + @property + def num_constraint_tokens(self): + return sum(self.token_counts.values()) + + def next_tokens(self) -> Set[int]: + """Returns the list of tokens that could come next. + These are (a) all tokens extending the root state and, for + non-root states, additionally all tokens extending the current + state.""" + + if self.node != self.root: + return self.root.next_tokens().union(self.node.next_tokens()) + else: + return self.root.next_tokens() + + def advance(self, token: int): + """Reads in a token and advances the state. Here's how it works. + + We can advance to the next state if: + - there is a matching child + - its path isn't blocked + + A path is blocked when all constraints that are descendants of + that node have already been generated, in the current state. + + If we are not able to advance from the current state, we "fall + off the graph" and return to the root state. There, we again + try to advance, checking the same criteria. + + In any case, when falling off the graph, we need to do some + bookkeeping. We: + - check whether any constraints were met (all prefixes of + current state) + - if one is found, mark it as completed + - adjust visited nodes accordingly + """ + token = int(token) + + next_state = None + child = self.node[token] + if child is not None and self.generated[child] < child.num_constraints: + next_state = UnorderedConstraintState(child, copy_from=self) + + def rewind(): + """If we're mid-trie and an "illegal" token is chosen next, we need + to reset our state to the root state. However, along the way, we need + to check whether a prefix of the current trie state represents a state + we could mark as completed. + """ + node = self.node + while node != self.root: + if node.terminal and self.completed[node] < node.terminal: + next_state.completed[node] += 1 + return + + next_state.generated[node] -= 1 + node = node.parent + + # Fall off the graph, check the root + if next_state is None and token in self.root.next_tokens(): + child = self.root[token] + # We can only traverse this edge if it's not saturated + if self.generated[child] < child.num_constraints: + next_state = UnorderedConstraintState(child, copy_from=self) + else: + next_state = UnorderedConstraintState(self.root, copy_from=self) + + # Rewind + rewind() + + elif next_state is None: + next_state = UnorderedConstraintState(self.root, copy_from=self) + # Rewind + rewind() + + return next_state + + +class ConstraintSequence: + def __init__(self, sequences: List[List[int]]): + """Represents a set of possibly multitoken constraints by + concatenating them and internally recording the end points. + """ + self.sequences = [] + self.endpoints = [] + self.num_tokens = 0 + self.tokens = set() + for sequence in sequences: + for token in sequence: + self.tokens.add(token) + self.num_tokens += len(sequence) + self.endpoints += [False for x in range(len(sequence) - 1)] + [True] + self.sequences += sequence + + def __getitem__(self, key: int): + return self.sequences[key] + + def __len__(self): + return len(self.sequences) + + def __str__(self): + return str(self.sequences) + + +class OrderedConstraintState(ConstraintState): + """ + Records progress through the set of linear nonbranching constraints with gaps. + """ + + def __init__(self, sequence: ConstraintSequence, state: int = -1): + self.sequence = sequence + self.state = state + + @staticmethod + def create(constraint_tensor: torch.Tensor): + constraint_list = unpack_constraints(constraint_tensor) + return OrderedConstraintState(ConstraintSequence(constraint_list), -1) + + def __str__(self): + return f"{self.state}/{self.bank}x{self.num_completed}" + + def __copy__(self): + return OrderedConstraintState(self.sequence, self.state) + + def copy(self): + return self.__copy__() + + @property + def num_completed(self): + if self.state == -1: + return 0 + count = len( + list(filter(lambda x: x, self.sequence.endpoints[0 : self.state + 1])) + ) + return count + + @property + def is_root(self): + return self.state == -1 + + @property + def name(self): + if self.state == -1: + return "ROOT" + else: + return str(self.sequence[self.state]) + + @property + def bank(self) -> int: + return self.state + 1 + + @property + def finished(self): + return self.state + 1 == len(self.sequence) + + @property + def token_counts(self): + return self.sequence.token_counts() + + @property + def tokens(self): + return self.sequence.tokens + + @property + def num_constraint_tokens(self): + return sum(self.token_counts.values()) + + def next_tokens(self) -> Set[int]: + """Returns the list of tokens that could come next. + These are (a) all tokens extending the root state and, for + non-root states, additionally all tokens extending the current + state.""" + + tokens = set() + if self.state > 0: + tokens.add(self.sequence[0]) + if not self.finished: + tokens.add(self.sequence[self.state + 1]) + return tokens + + def advance(self, token: int): + """Reads in a token and advances the state. Here's how it works. + + We can advance to the next state if: + - there is a matching child + - its path isn't blocked + + A path is blocked when all constraints that are descendants of + that node have already been generated, in the current state. + + If we are not able to advance from the current state, we "fall + off the graph" and return to the root state. There, we again + try to advance, checking the same criteria. + + In any case, when falling off the graph, we need to do some + bookkeeping. We: + - check whether any constraints were met (all prefixes of + current state) + - if one is found, mark it as completed + - adjust visited nodes accordingly + """ + token = int(token) + # print(f"{self} ADVANCE({token}) {self.sequence} -> ", end="") + + if self.finished: + # Accept anything + next_state = self.copy() + + elif self.sequence[self.state + 1] == token: + # Advance to the next token + next_state = OrderedConstraintState(self.sequence, self.state + 1) + + elif self.sequence.endpoints[self.state]: + # Accept anything between constraints (*) + next_state = self.copy() + + elif token == self.sequence[0]: + # Start over having generated the first token + next_state = OrderedConstraintState(self.sequence, 0) + else: + # Start over from the root + next_state = OrderedConstraintState(self.sequence, -1) + + return next_state diff --git a/PyTorch/NLP/new-Transformer/fairseq/tokenizer.py b/PyTorch/NLP/new-Transformer/fairseq/tokenizer.py new file mode 100644 index 00000000..42131f7b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/tokenizer.py @@ -0,0 +1,15 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import re + + +SPACE_NORMALIZER = re.compile(r"\s+") + + +def tokenize_line(line): + line = SPACE_NORMALIZER.sub(" ", line) + line = line.strip() + return line.split() diff --git a/PyTorch/NLP/new-Transformer/fairseq/trainer.py b/PyTorch/NLP/new-Transformer/fairseq/trainer.py new file mode 100644 index 00000000..031e4a70 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/trainer.py @@ -0,0 +1,1593 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +""" +Train a network across multiple GPUs. +""" + +import contextlib +import logging +import os +import sys +import time +from argparse import Namespace +from itertools import chain +from typing import Any, Dict, List + +import torch +from omegaconf import OmegaConf + +from fairseq import checkpoint_utils, models, optim, utils +from fairseq.dataclass.configs import FairseqConfig +from fairseq.dataclass.utils import convert_namespace_to_omegaconf +from fairseq.distributed import utils as distributed_utils +from fairseq.file_io import PathManager +from fairseq.logging import meters, metrics +from fairseq.models.ema import build_ema +from fairseq.nan_detector import NanDetector +from fairseq.optim import lr_scheduler +from fairseq.utils import safe_hasattr + +logger = logging.getLogger(__name__) + + +class Trainer(object): + """Main class for data parallel training. + + This class supports synchronous distributed data parallel training, + where multiple workers each have a full model replica and gradients + are accumulated across workers before each update. We use + :class:`~torch.nn.parallel.DistributedDataParallel` to handle + communication of the gradients across workers. + """ + + def __init__(self, cfg: FairseqConfig, task, model, criterion, quantizer=None): + + if isinstance(cfg, Namespace): + logger.warning( + "argparse.Namespace configuration is deprecated! Automatically converting to OmegaConf" + ) + cfg = convert_namespace_to_omegaconf(cfg) + + self.cfg = cfg + self.task = task + + # catalog shared parameters + shared_params = _catalog_shared_params(model) + self.tpu = cfg.common.tpu + self.cuda = torch.cuda.is_available() and not cfg.common.cpu and not self.tpu + if self.cuda: + self.device = torch.device("cuda") + elif self.tpu: + self.device = utils.get_tpu_device() + else: + self.device = torch.device("cpu") + + if self.is_fsdp: + import fairscale + + if self.cfg.common.bf16: + raise ValueError( + "FullyShardedDataParallel is not compatible with --bf16 or " + "--memory-efficient-bf16" + ) + if self.cfg.distributed_training.zero_sharding != "none": + raise ValueError( + "FullyShardedDataParallel is not compatible with --zero-sharding " + "option (it's already built in)" + ) + if ( + max(self.cfg.optimization.update_freq) > 1 + and fairscale.__version__ < "0.4.0" + ): + raise RuntimeError( + "Please update to fairscale 0.4.0 or newer when combining " + "--update-freq with FullyShardedDataParallel" + ) + else: + if ( + hasattr(self.cfg.distributed_training, "cpu_offload") + and self.cfg.distributed_training.cpu_offload + ): + raise ValueError("--cpu-offload requires --ddp-backend=fully_sharded") + + # copy model and criterion to current device/dtype + self._criterion = criterion + self._model = model + if not self.is_fsdp: + if cfg.common.fp16: + assert not cfg.common.amp, "Cannot use fp16 and AMP together" + self._criterion = self._criterion.half() + self._model = self._model.half() + elif cfg.common.bf16: + self._criterion = self._criterion.to(dtype=torch.bfloat16) + self._model = self._model.to(dtype=torch.bfloat16) + elif cfg.common.amp: + self._amp_retries = 0 + if ( + not cfg.distributed_training.pipeline_model_parallel + # the DistributedFairseqModel wrapper will handle moving to device, + # so only handle cases which don't use the wrapper + and not self.use_distributed_wrapper + ): + self._criterion = self._criterion.to(device=self.device) + self._model = self._model.to(device=self.device) + self.pipeline_model_parallel = cfg.distributed_training.pipeline_model_parallel + self.last_device = None + if self.cuda and self.pipeline_model_parallel: + self.last_device = torch.device( + cfg.distributed_training.pipeline_devices[-1] + ) + + # check that shared parameters are preserved after device transfer + for shared_param in shared_params: + ref = _get_module_by_path(self._model, shared_param[0]) + for path in shared_param[1:]: + logger.info( + "detected shared parameter: {} <- {}".format(shared_param[0], path) + ) + _set_module_by_path(self._model, path, ref) + + self._dummy_batch = None # indicates we don't have a dummy batch at first + self._lr_scheduler = None + self._num_updates = 0 + self._num_xla_compiles = 0 # for TPUs + self._optim_history = None + self._optimizer = None + self._warn_once = set() + self._wrapped_criterion = None + self._wrapped_model = None + self._ema = None + + # TODO(myleott): support tpu + if self.cuda and self.data_parallel_world_size > 1: + self._grad_norm_buf = torch.cuda.DoubleTensor(self.data_parallel_world_size) + else: + self._grad_norm_buf = None + + self.quantizer = quantizer + if self.quantizer is not None: + self.quantizer.set_trainer(self) + + # get detailed cuda environment + if self.cuda: + self.cuda_env = utils.CudaEnvironment() + if self.data_parallel_world_size > 1: + self.cuda_env_arr = distributed_utils.all_gather_list( + self.cuda_env, group=distributed_utils.get_global_group() + ) + else: + self.cuda_env_arr = [self.cuda_env] + if self.data_parallel_rank == 0: + utils.CudaEnvironment.pretty_print_cuda_env_list(self.cuda_env_arr) + else: + self.cuda_env = None + self.cuda_env_arr = None + + metrics.log_start_time("wall", priority=790, round=0) + + self._start_time = time.time() + self._previous_training_time = 0 + self._cumulative_training_time = None + + def reinitialize(self): + """Reinitialize the Trainer, typically after model params change.""" + self._lr_scheduler = None + self._optimizer = None + self._wrapped_criterion = None + self._wrapped_model = None + + @property + def data_parallel_world_size(self): + if self.cfg.distributed_training.distributed_world_size == 1: + return 1 + return distributed_utils.get_data_parallel_world_size() + + @property + def data_parallel_process_group(self): + return distributed_utils.get_data_parallel_group() + + @property + def data_parallel_rank(self): + if self.cfg.distributed_training.distributed_world_size == 1: + return 0 + return distributed_utils.get_data_parallel_rank() + + @property + def is_data_parallel_master(self): + # NOTE: this returns true for all model parallel replicas with data + # parallel rank 0 + return self.data_parallel_rank == 0 + + @property + def use_distributed_wrapper(self) -> bool: + return ( + self.data_parallel_world_size > 1 and not self.cfg.optimization.use_bmuf + ) or (self.is_fsdp and self.cfg.distributed_training.cpu_offload) + + @property + def should_save_checkpoint_on_current_rank(self) -> bool: + """Indicates whether to save checkpoints on the current DDP rank.""" + if ( + self.is_fsdp and self.cfg.distributed_training.use_sharded_state + ) or getattr(self.cfg.model, "base_layers", 0) > 0: + return True + else: + return self.is_data_parallel_master + + @property + def always_call_state_dict_during_save_checkpoint(self) -> bool: + if self.is_fsdp and not self.cfg.distributed_training.use_sharded_state: + # FSDP calls communication collective when consolidating checkpoints + return True + else: + return False + + @property + def checkpoint_suffix(self) -> str: + """Suffix to add to the checkpoint file name.""" + if self.is_fsdp and self.cfg.distributed_training.use_sharded_state: + return self.cfg.checkpoint.checkpoint_suffix + "-shard{0}".format( + self.data_parallel_rank + ) + else: + return self.cfg.checkpoint.checkpoint_suffix or "" + + @property + def criterion(self): + if self._wrapped_criterion is None: + if utils.has_parameters(self._criterion) and self.use_distributed_wrapper: + self._wrapped_criterion = models.DistributedFairseqModel( + self.cfg.distributed_training, + self._criterion, + process_group=self.data_parallel_process_group, + device=self.device, + ) + else: + self._wrapped_criterion = self._criterion + return self._wrapped_criterion + + @property + def model(self): + if self._wrapped_model is None: + if self.use_distributed_wrapper: + self._wrapped_model = models.DistributedFairseqModel( + self.cfg.distributed_training, + self._model, + process_group=self.data_parallel_process_group, + device=self.device, + ) + else: + self._wrapped_model = self._model + return self._wrapped_model + + @property + def ema(self): + if self._ema is None: + self._build_ema() + return self._ema + + def _build_ema(self): + if self.cfg.ema.store_ema: + self._ema = build_ema(self._model, self.cfg.ema, self.device) + logger.info("Exponential Moving Average Shadow Model is initialized.") + + @property + def optimizer(self): + if self._optimizer is None: + self._build_optimizer() + return self._optimizer + + @property + def lr_scheduler(self): + if self._lr_scheduler is None: + self._build_optimizer() # this will initialize self._lr_scheduler + return self._lr_scheduler + + def _build_optimizer(self): + params = list( + filter( + lambda p: p.requires_grad, + chain(self.model.parameters(), self.criterion.parameters()), + ) + ) + + if self.is_fsdp and self.cfg.common.fp16: + # FullyShardedDataParallel always uses MemoryEfficientFP16 wrapper, + # mostly for the grad scaling. But if we don't have the + # --memory-efficient-fp16 flag set, then we're effectively doing + # regular --fp16 and can allow the use of optimizers that would + # otherwise be unsupported by MemoryEfficientFP16Optimizer. + allow_unsupported = not self.cfg.common.memory_efficient_fp16 + self._optimizer = optim.MemoryEfficientFP16Optimizer.build_optimizer( + self.cfg, params, allow_unsupported=allow_unsupported + ) + elif self.cfg.common.fp16 or self.cfg.common.bf16 or self.cfg.common.amp: + if self.cuda and torch.cuda.get_device_capability(0)[0] < 7: + logger.info( + "NOTE: your device does NOT support faster training with --fp16 or --amp, " + "please switch to FP32 which is likely to be faster" + ) + if ( + self.cfg.common.memory_efficient_fp16 + or self.cfg.common.memory_efficient_bf16 + ): + self._optimizer = optim.MemoryEfficientFP16Optimizer.build_optimizer( + self.cfg, params + ) + elif self.cfg.common.amp: + self._optimizer = optim.AMPOptimizer.build_optimizer(self.cfg, params) + else: + self._optimizer = optim.FP16Optimizer.build_optimizer(self.cfg, params) + else: + if self.cuda and torch.cuda.get_device_capability(0)[0] >= 7: + logger.info( + "NOTE: your device may support faster training with --fp16 or --amp" + ) + self._optimizer = optim.build_optimizer(self.cfg.optimizer, params) + + if self.is_fsdp: + assert ( + not self.cfg.optimization.use_bmuf + ), "--ddp-backend=fully_sharded is not compatible with BMUF" + assert self._optimizer.supports_flat_params, ( + "--ddp-backend=fully_sharded is only compatible with pointwise " + "optimizers (e.g., Adam, AdamW, Adadelta, Adamax, SGD, etc.). " + "However, the sharding will result in slightly different results when " + "using non-pointwise optimizers (e.g., Adagrad, Adafactor, LAMB)" + ) + + if self.cfg.optimization.use_bmuf: + self._optimizer = optim.FairseqBMUF( + self.cfg.bmuf, + self._optimizer, + ) + + if self.cfg.distributed_training.zero_sharding == "os": + if ( + self.cfg.common.fp16 + and not self.cfg.common.memory_efficient_fp16 + and not self.cfg.common.memory_efficient_bf16 + ) and not self.cfg.common.fp16_no_flatten_grads: + raise ValueError( + "ZeRO is incomptabile with fp16 and flattened grads. " + "Please use --fp16-no-flatten-grads" + ) + else: + optim.shard_(self._optimizer, self.data_parallel_process_group) + + # We should initialize the learning rate scheduler immediately after + # building the optimizer, so that the initial learning rate is set. + self._lr_scheduler = lr_scheduler.build_lr_scheduler( + self.cfg.lr_scheduler, + self.optimizer, + ) + self._lr_scheduler.step_update(0) + + @property + def is_fsdp(self): + return self.cfg.distributed_training.ddp_backend == "fully_sharded" + + def consolidate_optimizer(self): + """For OSS, we need to consolidate the state dict.""" + if self.cfg.checkpoint.no_save_optimizer_state: + return + self._gathered_optim_state = None + if hasattr(self.optimizer.optimizer, "consolidate_state_dict"): + self.optimizer.optimizer.consolidate_state_dict() + elif self.is_fsdp and not self.model.use_sharded_state: + st = self.model.gather_full_optim_state_dict( + self.optimizer + ) # only returns on rank 0 + self._gathered_optim_state = st + + def state_dict(self): + state_dict = { + "args": None, # legacy + "cfg": ( + OmegaConf.to_container(self.cfg, resolve=True, enum_to_str=True) + if OmegaConf.is_config(self.cfg) + else self.cfg + ), + "model": self.model.state_dict(), + "criterion": ( + self.criterion.state_dict() + if utils.has_parameters(self.criterion) + else None + ), + "optimizer_history": (self._optim_history or []) + + [ + { + "criterion_name": self.get_criterion().__class__.__name__, + "optimizer_name": self.optimizer.__class__.__name__, + "lr_scheduler_state": self.lr_scheduler.state_dict(), + "num_updates": self.get_num_updates(), + } + ], + "task_state": self.task.state_dict() if self.task is not None else {}, + "extra_state": { + "metrics": metrics.state_dict(), + "previous_training_time": self.cumulative_training_time(), + }, + } + if self.cfg.ema.store_ema: + # Save EMA model state as extra state + state_dict["extra_state"]["ema"] = self.ema.get_model().state_dict() + if self.cfg.ema.ema_fp32: + # Save EMA params in fp32 + state_dict["extra_state"]["ema_fp32_params"] = self.ema.fp32_params + if not self.cfg.checkpoint.no_save_optimizer_state: + if self._gathered_optim_state is not None: + state_dict["last_optimizer_state"] = self._gathered_optim_state + self._gathered_optim_state = None + else: + state_dict["last_optimizer_state"] = self.optimizer.state_dict() + if self.is_fsdp: + # save meta data for recombining checkpoint upon loading + state_dict["fsdp_metadata"] = self.model.local_metadata_dict() + return state_dict + + def save_checkpoint(self, filename, extra_state): + """Save all training state in a checkpoint file.""" + + logger.info(f"Saving checkpoint to {os.path.abspath(filename)}") + # call state_dict on all ranks in case it needs internal communication + state_dict = utils.move_to_cpu(self.state_dict()) + state_dict["extra_state"].update(extra_state) + if self.should_save_checkpoint_on_current_rank: + checkpoint_utils.torch_persistent_save( + state_dict, + filename, + async_write=self.cfg.checkpoint.write_checkpoints_asynchronously, + ) + logger.info(f"Finished saving checkpoint to {os.path.abspath(filename)}") + + def load_checkpoint( + self, + filename, + reset_optimizer=False, + reset_lr_scheduler=False, + optimizer_overrides=None, + reset_meters=False, + ): + """ + Load all training state from a checkpoint file. + rank = 0 will load the checkpoint, and then broadcast it to all + other ranks. + """ + extra_state, self._optim_history, last_optim_state = None, [], None + + logger.info(f"Preparing to load checkpoint {filename}") + is_distributed = self.data_parallel_world_size > 1 + bexists = PathManager.isfile(filename) + if bexists: + load_on_all_ranks = ( + self.cfg.checkpoint.load_checkpoint_on_all_dp_ranks + # TPUs don't support broadcast yet, so load checkpoints + # on every worker for now + or self.tpu + # FSDP requires loading checkpoint shards on all ranks + or (self.is_fsdp and self.cfg.distributed_training.use_sharded_state) + or getattr(self.cfg.model, "base_layers", 0) > 0 + ) + + if load_on_all_ranks or self.data_parallel_rank == 0: + state = checkpoint_utils.load_checkpoint_to_cpu( + filename, load_on_all_ranks=load_on_all_ranks + ) + last_optim_state = state.get("last_optimizer_state", None) + + # If doing zero_sharding, do not broadcast global optimizer + # state. Later we will broadcast sharded states to each rank + # to avoid memory from exploding. + if ( + not load_on_all_ranks + and self.cfg.distributed_training.zero_sharding == "os" + and "last_optimizer_state" in state + and is_distributed + ): + state["last_optimizer_state"] = "SHARDED" + else: + last_optim_state = None + state = None + + if is_distributed and not load_on_all_ranks: + state = distributed_utils.broadcast_object( + state, + src_rank=0, + group=self.data_parallel_process_group, + dist_device=self.device, + ) + if self.data_parallel_rank > 0: + last_optim_state = state.get("last_optimizer_state", None) + + # load model parameters + try: + if ( + "optimizer_history" in state + and len(state["optimizer_history"]) > 0 + and "num_updates" in state["optimizer_history"][-1] + ): + self.model.set_num_updates( + state["optimizer_history"][-1]["num_updates"] + ) + + # this is the code related to AdaPrune + # In short, it removes redundant heads in multi-head attention module based on heads importance provided + # For more info, please refer to the paper: https://openreview.net/forum?id=_CMSV7FTzGI + # The idea of prune in mha can be summarized as + # Fine tune model (e.g. roberta encoder) on a certain datasets with regularization + # After the model is trained. User could use get_reserve_head_index and _adaptive_prune_heads functions to get the top X heads with most importance. + # Then user uses the rank to prune a new roberta encoder and save the pruned ckpt manually. + # User will fine tune the the new roberta encoder via the ckpt saved above + # To get rid of registering different pruned version of Roberta, I use the argument --mha-heads-to-keep to prune the Roberta model into a pruned version which matches the pruned ckpt. + if ( + safe_hasattr(self.model, "args") + and safe_hasattr(self.model.args, "mha_heads_to_keep") + and self.model.args.mha_heads_to_keep != -1 + ): + logger.info( + f"Prune model: keep {self.model.args.mha_heads_to_keep} heads for each multihead attention module" + ) + for layer in self.model.encoder.sentence_encoder.layers: + reserve_head_index = layer.self_attn._get_reserve_head_index( + num_heads_to_keep=self.model.args.mha_heads_to_keep + ) + layer.self_attn._adaptive_prune_heads( + reserve_head_index=reserve_head_index + ) + layer.self_attn._set_skip_embed_dim_check() + logger.info(self.model) + # this is the code related to AdaPrune + # In short, it removes redundant units in feedforward layer in each transformer layer based on importance + # For more info, please refer to the paper: https://openreview.net/forum?id=_CMSV7FTzGI + # The idea of prune in ffn can be summarized as + # Fine tune model (e.g. roberta encoder) on a certain datasets with regularization + # After the model is trained. User could use _get_fc_rank and _prune_fc_layer functions to get the top X units with most importance. + # Then user uses the rank to prune a new roberta encoder and save the pruned ckpt manually. + # User will fine tune the the new roberta encoder via the ckpt saved above + # To get rid of registering different pruned version of Roberta, I use the argument --ffn-blocks-to-remove to prune the Roberta model into a pruned version which matches the pruned ckpt. + if ( + safe_hasattr(self.model, "args") + and safe_hasattr(self.model.args, "ffn_blocks_to_remove") + and self.model.args.ffn_blocks_to_remove != -1 + ): + logger.info( + f"Prune model: remove {self.model.args.ffn_blocks_to_remove} ffn blocks for each transformer layer" + ) + for layer in self.model.encoder.sentence_encoder.layers: + remove_index = layer._get_fc_rank( + remove_num=self.model.args.ffn_blocks_to_remove + ) + layer._prune_fc_layer(remove_index=remove_index) + logger.info(self.model) + + self.model.load_state_dict( + state["model"], strict=True, model_cfg=self.cfg.model + ) + # save memory for later steps + del state["model"] + if utils.has_parameters(self.get_criterion()): + self.get_criterion().load_state_dict( + state["criterion"], strict=True + ) + del state["criterion"] + + except Exception: + raise Exception( + "Cannot load model parameters from checkpoint {}; " + "please ensure that the architectures match.".format(filename) + ) + extra_state = state["extra_state"] + self._optim_history = state["optimizer_history"] + + if last_optim_state is not None and not reset_optimizer: + # rebuild optimizer after loading model, since params may have changed + self._build_optimizer() + + # only reload optimizer and lr_scheduler if they match + last_optim = self._optim_history[-1] + assert ( + last_optim["criterion_name"] == self.get_criterion().__class__.__name__ + ), f"Criterion does not match; please reset the optimizer (--reset-optimizer). {last_optim['criterion_name']} vs {self.get_criterion().__class__.__name__}" + assert ( + last_optim["optimizer_name"] == self.optimizer.__class__.__name__ + ), f"Optimizer does not match; please reset the optimizer (--reset-optimizer). {last_optim['optimizer_name']} vs {self.optimizer.__class__.__name__}" + + if not reset_lr_scheduler: + self.lr_scheduler.load_state_dict(last_optim["lr_scheduler_state"]) + + if self.is_fsdp and not self.model.use_sharded_state: + # if use_sharded_state, the last_optim_state is already sharded, skip this + last_optim_state = self.model.get_shard_from_optim_state_dict( + last_optim_state + ) + elif not load_on_all_ranks and is_distributed: + last_optim_state = self.optimizer.broadcast_global_state_dict( + last_optim_state + ) + + self.optimizer.load_state_dict(last_optim_state, optimizer_overrides) + + self.set_num_updates(last_optim["num_updates"]) + + if extra_state is not None: + itr_state = extra_state["train_iterator"] + epoch = itr_state["epoch"] + + if "previous_training_time" in extra_state: + self._previous_training_time = extra_state["previous_training_time"] + self._start_time = time.time() + + self.lr_step(epoch) + + if ( + itr_state.get("version", 1) >= 2 + and itr_state["iterations_in_epoch"] == 0 + ): + # reset meters at start of epoch + reset_meters = True + + if "metrics" in extra_state and not reset_meters: + metrics.load_state_dict(extra_state["metrics"]) + + # reset TimeMeters, since their start times don't make sense anymore + for meter in metrics.get_meters("default"): + if isinstance(meter, meters.TimeMeter): + meter.reset() + + if self.cfg.ema.store_ema: + if "ema" not in extra_state: + logger.warn( + "EMA not found in checkpoint. But store_ema is True. " + "EMA is re-initialized from checkpoint." + ) + self.ema.restore( + state["model"], build_fp32_params=self.cfg.ema.ema_fp32 + ) + else: + logger.info("Loading EMA from checkpoint") + self.ema.restore(extra_state["ema"], build_fp32_params=False) + + if self.cfg.ema.ema_fp32: + if "ema_fp32_params" in extra_state: + logger.info("Loading EMA fp32 params from checkpoint") + self.ema.build_fp32_params(extra_state["ema_fp32_params"]) + else: + logger.info( + "Building EMA fp32 params from EMA model in checkpoint" + ) + self.ema.build_fp32_params() + + logger.info( + "Loaded checkpoint {} (epoch {} @ {} updates)".format( + filename, epoch, self.get_num_updates() + ) + ) + + else: + logger.info("No existing checkpoint found {}".format(filename)) + + return extra_state + + def get_train_iterator( + self, + epoch, + combine=True, + load_dataset=True, + data_selector=None, + shard_batch_itr=True, + disable_iterator_cache=False, + ): + """Return an EpochBatchIterator over the training set for a given epoch.""" + if load_dataset: + logger.info("loading train data for epoch {}".format(epoch)) + self.task.load_dataset( + self.cfg.dataset.train_subset, + epoch=epoch, + combine=combine, + data_selector=data_selector, + tpu=self.tpu, + ) + batch_iterator = self.task.get_batch_iterator( + dataset=self.task.dataset(self.cfg.dataset.train_subset), + max_tokens=self.cfg.dataset.max_tokens, + max_sentences=self.cfg.dataset.batch_size, + max_positions=utils.resolve_max_positions( + self.task.max_positions(), + self.model.max_positions(), + self.cfg.dataset.max_tokens, + ), + ignore_invalid_inputs=True, + required_batch_size_multiple=self.cfg.dataset.required_batch_size_multiple, + seed=(self.cfg.common.seed + epoch) + if self.cfg.dataset.update_ordered_indices_seed + else self.cfg.common.seed, + num_shards=self.data_parallel_world_size if shard_batch_itr else 1, + shard_id=self.data_parallel_rank if shard_batch_itr else 0, + num_workers=self.cfg.dataset.num_workers, + epoch=epoch, + data_buffer_size=self.cfg.dataset.data_buffer_size, + disable_iterator_cache=disable_iterator_cache, + skip_remainder_batch=self.cfg.optimization.skip_remainder_batch, + grouped_shuffling=self.cfg.dataset.grouped_shuffling, + update_epoch_batch_itr=self.cfg.dataset.update_epoch_batch_itr, + ) + self.reset_dummy_batch(batch_iterator.first_batch) + return batch_iterator + + def get_valid_iterator( + self, + subset, + disable_iterator_cache=False, + ): + """Return an EpochBatchIterator over given validation subset for a given epoch.""" + batch_iterator = self.task.get_batch_iterator( + dataset=self.task.dataset(subset), + max_tokens=self.cfg.dataset.max_tokens_valid, + max_sentences=self.cfg.dataset.batch_size_valid, + max_positions=utils.resolve_max_positions( + self.task.max_positions(), + self.model.max_positions(), + ), + ignore_invalid_inputs=self.cfg.dataset.skip_invalid_size_inputs_valid_test, + required_batch_size_multiple=self.cfg.dataset.required_batch_size_multiple, + seed=self.cfg.common.seed, + num_shards=self.data_parallel_world_size, + shard_id=self.data_parallel_rank, + num_workers=self.cfg.dataset.num_workers, + # always pass a fixed "epoch" to keep validation data consistent + # across training epochs + epoch=1, + data_buffer_size=self.cfg.dataset.data_buffer_size, + disable_iterator_cache=disable_iterator_cache, + skip_remainder_batch=False, + ) + self.reset_dummy_batch(batch_iterator.first_batch) + return batch_iterator + + def begin_epoch(self, epoch): + """Called at the beginning of each epoch.""" + logger.info("begin training epoch {}".format(epoch)) + + self.lr_step_begin_epoch(epoch) + + if self.quantizer is not None: + self.quantizer.begin_epoch(epoch) + + # task specific setup per epoch + self.task.begin_epoch(epoch, self.get_model()) + + if self.tpu: + import torch_xla.core.xla_model as xm + + xm.rendezvous("begin_epoch") # wait for all workers + xm.mark_step() + + def begin_valid_epoch(self, epoch): + """Called at the beginning of each validation epoch.""" + + # task specific setup per validation epoch + self.task.begin_valid_epoch(epoch, self.get_model()) + + def reset_dummy_batch(self, batch): + self._dummy_batch = batch + + @metrics.aggregate("train") + def train_step(self, samples, raise_oom=False): + """Do forward, backward and parameter update.""" + self._set_seed() + self.model.train() + self.criterion.train() + self.zero_grad() + + metrics.log_start_time("train_wall", priority=800, round=0) + + # If EMA is enabled through store_ema=True + # and task.uses_ema is True, pass the EMA model as a keyword + # argument to the task. + extra_kwargs = {} + if self.cfg.ema.store_ema and getattr(self.task, "uses_ema", False): + extra_kwargs["ema_model"] = self.ema.get_model() + + # forward and backward pass + logging_outputs, sample_size, ooms = [], 0, 0 + for i, sample in enumerate(samples): # delayed update loop + sample, is_dummy_batch = self._prepare_sample(sample) + + def maybe_no_sync(): + """ + Whenever *samples* contains more than one mini-batch, we + want to accumulate gradients locally and only call + all-reduce in the last backwards pass. + """ + if ( + self.data_parallel_world_size > 1 + and hasattr(self.model, "no_sync") + and i < len(samples) - 1 + # The no_sync context manager results in increased memory + # usage with FSDP, since full-size gradients will be + # accumulated on each GPU. It's typically a better tradeoff + # to do the extra communication with FSDP. + and not self.is_fsdp + ): + return self.model.no_sync() + else: + return contextlib.ExitStack() # dummy contextmanager + + try: + with maybe_no_sync(): + # forward and backward + loss, sample_size_i, logging_output = self.task.train_step( + sample=sample, + model=self.model, + criterion=self.criterion, + optimizer=self.optimizer, + update_num=self.get_num_updates(), + ignore_grad=is_dummy_batch, + **extra_kwargs, + ) + #print(prof.key_averages().table()) + del loss + #改 + #prof.export_chrome_trace('./result_profile.json') + + logging_outputs.append(logging_output) + sample_size += sample_size_i + + # emptying the CUDA cache after the first step can + # reduce the chance of OOM + if self.cuda and self.get_num_updates() == 0: + torch.cuda.empty_cache() + except RuntimeError as e: + if "out of memory" in str(e): + self._log_oom(e) + if raise_oom: + raise e + logger.warning( + "attempting to recover from OOM in forward/backward pass" + ) + ooms += 1 + self.zero_grad() + if self.cuda: + torch.cuda.empty_cache() + if self.cfg.distributed_training.distributed_world_size == 1: + return None + else: + raise e + except Exception: + self.consolidate_optimizer() + self.save_checkpoint( + os.path.join(self.cfg.checkpoint.save_dir, "crash.pt"), {} + ) + raise + + if self.tpu and i < len(samples) - 1: + # tpu-comment: every XLA operation before marking step is + # appended to the IR graph, and processing too many batches + # before marking step can lead to OOM errors. + # To handle gradient accumulation use case, we explicitly + # mark step here for every forward pass without a backward pass + self._xla_markstep_and_send_to_cpu() + + if is_dummy_batch: + if torch.is_tensor(sample_size): + sample_size.zero_() + else: + sample_size *= 0.0 + + if torch.is_tensor(sample_size): + sample_size = sample_size.float() + else: + sample_size = float(sample_size) + + # gather logging outputs from all replicas + if self._sync_stats(): + train_time = self._local_cumulative_training_time() + ( + logging_outputs, + ( + sample_size, + ooms, + total_train_time, + ), + ) = self._aggregate_logging_outputs( + logging_outputs, sample_size, ooms, train_time, ignore=is_dummy_batch + ) + self._cumulative_training_time = ( + total_train_time / self.data_parallel_world_size + ) + + overflow = False + try: + with torch.autograd.profiler.record_function("reduce-grads"): + # reduce gradients across workers + self.optimizer.all_reduce_grads(self.model) + if utils.has_parameters(self.criterion): + self.optimizer.all_reduce_grads(self.criterion) + + with torch.autograd.profiler.record_function("multiply-grads"): + # multiply gradients by (data_parallel_size / sample_size) since + # DDP normalizes by the number of data parallel workers for + # improved fp16 precision. + # Thus we get (sum_of_gradients / sample_size) at the end. + # In case of fp16, this step also undoes loss scaling. + # (Debugging note: Some optimizers perform this scaling on the + # fly, so inspecting model.parameters() or optimizer.params may + # still show the original, unscaled gradients.) + numer = ( + self.data_parallel_world_size + if not self.cfg.optimization.use_bmuf or self._sync_stats() + else 1 + ) + self.optimizer.multiply_grads(numer / (sample_size or 1.0)) + # Note: (sample_size or 1.0) handles the case of a zero gradient, in a + # way that avoids CPU/device transfers in case sample_size is a GPU or + # TPU object. The assumption is that the gradient itself is also 0. + + with torch.autograd.profiler.record_function("clip-grads"): + # clip grads + grad_norm = self.clip_grad_norm(self.cfg.optimization.clip_norm) + + # check that grad norms are consistent across workers + # on tpu check tensor is slow + if not self.tpu: + if ( + not self.cfg.optimization.use_bmuf + and self.cfg.distributed_training.ddp_backend != "slowmo" + ): + self._check_grad_norms(grad_norm) + if not torch.isfinite(grad_norm).all(): + # in case of AMP, if gradients are Nan/Inf then + # optimizer step is still required + if self.cfg.common.amp: + overflow = True + else: + # check local gradnorm single GPU case, trigger NanDetector + raise FloatingPointError("gradients are Nan/Inf") + + with torch.autograd.profiler.record_function("optimizer"): + # take an optimization step + self.task.optimizer_step( + self.optimizer, model=self.model, update_num=self.get_num_updates() + ) + if self.cfg.common.amp and overflow: + if self._amp_retries == self.cfg.common.amp_batch_retries: + logger.info("AMP: skipping this batch.") + self._amp_retries = 0 + else: + self._amp_retries += 1 + return self.train_step( + samples, raise_oom + ) # recursion to feed in same batch + + except FloatingPointError: + + self.consolidate_optimizer() + self.save_checkpoint( + os.path.join(self.cfg.checkpoint.save_dir, "crash.pt"), {} + ) + + # re-run the forward and backward pass with hooks attached to print + # out where it fails + self.zero_grad() + with NanDetector(self.get_model()): + for _, sample in enumerate(samples): + sample, _ = self._prepare_sample(sample) + self.task.train_step( + sample, + self.model, + self.criterion, + self.optimizer, + self.get_num_updates(), + ignore_grad=False, + **extra_kwargs, + ) + raise + except OverflowError as e: + overflow = True + logger.info( + f"NOTE: gradient overflow detected, ignoring gradient, {str(e)}" + ) + grad_norm = torch.tensor(0.0).cuda() + self.zero_grad() + except RuntimeError as e: + if "out of memory" in str(e): + self._log_oom(e) + logger.error("OOM during optimization, irrecoverable") + raise e + + # Some distributed wrappers (e.g., SlowMo) need access to the optimizer + # after the step + if hasattr(self.model, "perform_slowmo"): + self.model.perform_slowmo( + self.optimizer.optimizer, getattr(self.optimizer, "fp32_params", None) + ) + + logging_output = None + if not overflow or self.cfg.distributed_training.ddp_backend == "slowmo": + self.set_num_updates(self.get_num_updates() + 1) + + if self.cfg.ema.store_ema: + # Step EMA forward with new model. + self.ema.step( + self.get_model(), + self.get_num_updates(), + ) + metrics.log_scalar( + "ema_decay", + self.ema.get_decay(), + priority=10000, + round=5, + weight=0, + ) + + if self.tpu: + import torch_xla.core.xla_model as xm + + # mark step on TPUs + self._xla_markstep_and_send_to_cpu() + + # only log stats every log_interval steps + # this causes wps to be misreported when log_interval > 1 + logging_output = {} + if self.get_num_updates() % self.cfg.common.log_interval == 0: + # log memory usage + mem_info = xm.get_memory_info(self.device) + gb_free = mem_info["kb_free"] / 1024 / 1024 + gb_total = mem_info["kb_total"] / 1024 / 1024 + metrics.log_scalar( + "gb_free", gb_free, priority=1500, round=1, weight=0 + ) + metrics.log_scalar( + "gb_total", gb_total, priority=1600, round=1, weight=0 + ) + logging_outputs = self._xla_markstep_and_send_to_cpu( + logging_outputs + ) + logging_output = self._reduce_and_log_stats( + logging_outputs, sample_size, grad_norm + ) + + # log whenever there's an XLA compilation, since these + # slow down training and may indicate opportunities for + # optimization + self._check_xla_compilation() + else: + if self.cuda and self.cuda_env is not None: + # log minimum free memory over the iteration + gb_used = torch.cuda.max_memory_allocated() / 1024 / 1024 / 1024 + torch.cuda.reset_peak_memory_stats() + gb_free = self.cuda_env.total_memory_in_GB - gb_used + metrics.log_scalar( + "gb_free", gb_free, priority=1500, round=1, weight=0 + ) + + # log stats + logging_output = self._reduce_and_log_stats( + logging_outputs, sample_size, grad_norm + ) + + # clear CUDA cache to reduce memory fragmentation + if ( + self.cuda + and self.cfg.common.empty_cache_freq > 0 + and ( + (self.get_num_updates() + self.cfg.common.empty_cache_freq - 1) + % self.cfg.common.empty_cache_freq + ) + == 0 + ): + torch.cuda.empty_cache() + + if self.cfg.common.fp16 or self.cfg.common.amp: + metrics.log_scalar( + "loss_scale", + ( + self.optimizer.scaler.loss_scale + if self.cfg.common.fp16 + else self.optimizer.scaler.get_scale() + ), + priority=700, + round=4, + weight=0, + ) + + metrics.log_stop_time("train_wall") + return logging_output + + @metrics.aggregate("valid") + def valid_step(self, sample, raise_oom=False): + """Do forward pass in evaluation mode.""" + if self.tpu: + import torch_xla.core.xla_model as xm + + xm.rendezvous("valid_step") # wait for all workers + + # If EMA is enabled through store_ema=True + # and task.uses_ema is True, pass the EMA model as a keyword + # argument to the task. + extra_kwargs = {} + if self.cfg.ema.store_ema and getattr(self.task, "uses_ema", False): + extra_kwargs["ema_model"] = self.ema.get_model() + + with torch.no_grad(): + self.model.eval() + self.criterion.eval() + + sample, is_dummy_batch = self._prepare_sample(sample) + + try: + _loss, sample_size, logging_output = self.task.valid_step( + sample, self.model, self.criterion, **extra_kwargs + ) + except RuntimeError as e: + if "out of memory" in str(e): + self._log_oom(e) + if not raise_oom: + logger.warning( + "ran out of memory in validation step, retrying batch" + ) + for p in self.model.parameters(): + if p.grad is not None: + p.grad = None # free some memory + if self.cuda: + torch.cuda.empty_cache() + return self.valid_step(sample, raise_oom=True) + raise e + + logging_outputs = [logging_output] + if is_dummy_batch: + if torch.is_tensor(sample_size): + sample_size.zero_() + else: + sample_size *= 0.0 + + # gather logging outputs from all replicas + if self.data_parallel_world_size > 1: + logging_outputs, (sample_size,) = self._aggregate_logging_outputs( + logging_outputs, + sample_size, + ignore=is_dummy_batch, + ) + + # log validation stats + if self.tpu: + logging_outputs = self._xla_markstep_and_send_to_cpu(logging_outputs) + logging_output = self._reduce_and_log_stats(logging_outputs, sample_size) + + return logging_output + + def zero_grad(self): + self.optimizer.zero_grad() + + def lr_step_begin_epoch(self, epoch): + """Adjust the learning rate at the beginning of the epoch.""" + self.lr_scheduler.step_begin_epoch(epoch) + # prefer updating the LR based on the number of steps + return self.lr_step_update() + + def lr_step(self, epoch, val_loss=None): + """Adjust the learning rate at the end of the epoch.""" + self.lr_scheduler.step(epoch, val_loss) + # prefer updating the LR based on the number of steps + return self.lr_step_update() + + def lr_step_update(self): + """Update the learning rate after each update.""" + new_lr = self.lr_scheduler.step_update(self.get_num_updates()) + if isinstance(new_lr, dict): + for k, v in new_lr.items(): + metrics.log_scalar(f"lr_{k}", v, weight=0, priority=300) + new_lr = new_lr.get("default", next(iter(new_lr.values()))) + else: + metrics.log_scalar("lr", new_lr, weight=0, priority=300) + return new_lr + + def get_lr(self): + """Get the current learning rate.""" + return self.optimizer.get_lr() + + def get_model(self): + """Get the (non-wrapped) model instance.""" + return self._model + + def get_criterion(self): + """Get the (non-wrapped) criterion instance.""" + return self._criterion + + def get_meter(self, name): + """[deprecated] Get a specific meter by name.""" + from fairseq import meters + + if "get_meter" not in self._warn_once: + self._warn_once.add("get_meter") + utils.deprecation_warning( + "Trainer.get_meter is deprecated. Please use fairseq.metrics instead." + ) + + train_meters = metrics.get_meters("train") + if train_meters is None: + train_meters = {} + + if name == "train_loss" and "loss" in train_meters: + return train_meters["loss"] + elif name == "train_nll_loss": + # support for legacy train.py, which assumed this meter is + # always initialized + m = train_meters.get("nll_loss", None) + return m or meters.AverageMeter() + elif name == "wall": + # support for legacy train.py, which assumed this meter is + # always initialized + m = metrics.get_meter("default", "wall") + return m or meters.TimeMeter() + elif name == "wps": + m = metrics.get_meter("train", "wps") + return m or meters.TimeMeter() + elif name in {"valid_loss", "valid_nll_loss"}: + # support for legacy train.py, which assumed these meters + # are always initialized + k = name[len("valid_") :] + m = metrics.get_meter("valid", k) + return m or meters.AverageMeter() + elif name == "oom": + return meters.AverageMeter() + elif name in train_meters: + return train_meters[name] + return None + + def get_num_updates(self): + """Get the number of parameters updates.""" + return self._num_updates + + def set_num_updates(self, num_updates): + """Set the number of parameters updates.""" + self._num_updates = num_updates + self.lr_step_update() + if self.quantizer: + self.quantizer.step_update(self._num_updates) + metrics.log_scalar("num_updates", self._num_updates, weight=0, priority=200) + + def clip_grad_norm(self, clip_norm): + def agg_norm_fn(total_norm): + total_norm = total_norm.cuda().float() ** 2 + total_norm = distributed_utils.all_reduce( + total_norm, group=self.data_parallel_process_group + ) + return total_norm**0.5 + + should_agg_norm = self.is_fsdp and ( + self.data_parallel_process_group is not None + or torch.distributed.is_initialized() + ) + return self.optimizer.clip_grad_norm( + clip_norm, aggregate_norm_fn=agg_norm_fn if should_agg_norm else None + ) + + def cumulative_training_time(self): + if self._cumulative_training_time is None: + # single GPU + return self._local_cumulative_training_time() + else: + return self._cumulative_training_time + + def _local_cumulative_training_time(self): + """Aggregate training time in seconds.""" + return time.time() - self._start_time + self._previous_training_time + + def _fp_convert_sample(self, sample): + def apply_half(t): + if t.dtype is torch.float32: + return t.to(dtype=torch.half) + return t + + def apply_bfloat16(t): + if t.dtype is torch.float32: + return t.to(dtype=torch.bfloat16) + return t + + if self.cfg.common.fp16: + sample = utils.apply_to_sample(apply_half, sample) + + if self.cfg.common.bf16: + sample = utils.apply_to_sample(apply_bfloat16, sample) + + return sample + + def _prepare_sample(self, sample, is_dummy=False): + if sample == "DUMMY": + raise Exception( + "Trying to use an uninitialized 'dummy' batch. This usually indicates " + "that the total number of batches is smaller than the number of " + "participating GPUs. Try reducing the batch size or using fewer GPUs." + ) + + if sample is None or len(sample) == 0: + assert ( + self._dummy_batch is not None and len(self._dummy_batch) > 0 + ), "Invalid dummy batch: {}".format(self._dummy_batch) + sample, _ = self._prepare_sample(self._dummy_batch, is_dummy=True) + return sample, True + + # Given that PCIe/NVLink bandwidth is significantly smaller than DRAM bandwidth + # it makes sense to do the format conversion on the CPU and then transfer + # a smaller buffer to the device. This also saves GPU memory capacity. + + if self.cfg.common.on_cpu_convert_precision: + sample = self._fp_convert_sample(sample) + + if self.cuda: + if self.pipeline_model_parallel: + if "target" in sample: + sample["target"] = utils.move_to_cuda( + sample["target"], device=self.last_device + ) + else: + sample = utils.move_to_cuda(sample) + elif self.tpu and is_dummy: + # the dummy batch may not be on the appropriate device + sample = utils.move_to_cuda(sample, device=self.device) + + if not self.cfg.common.on_cpu_convert_precision: + sample = self._fp_convert_sample(sample) + + if self._dummy_batch == "DUMMY": + self._dummy_batch = sample + + return sample, False + + def _set_seed(self): + # Set seed based on args.seed and the update number so that we get + # reproducible results when resuming from checkpoints + seed = self.cfg.common.seed + self.get_num_updates() + utils.set_torch_seed(seed) + + def _sync_stats(self): + # Return True if it's using multiple GPUs and DDP or multiple GPUs with + # BMUF and it's a bmuf sync with warmup iterations completed before. + if self.data_parallel_world_size == 1: + return False + elif self.cfg.optimization.use_bmuf: + return ( + self.get_num_updates() + 1 + ) % self.cfg.bmuf.global_sync_iter == 0 and ( + self.get_num_updates() + 1 + ) > self.cfg.bmuf.warmup_iterations + else: + return True + + def _log_oom(self, exc): + msg = "OOM: Ran out of memory with exception: {}".format(exc) + logger.warning(msg) + if torch.cuda.is_available() and hasattr(torch.cuda, "memory_summary"): + for device_idx in range(torch.cuda.device_count()): + logger.warning(torch.cuda.memory_summary(device=device_idx)) + sys.stderr.flush() + + def _aggregate_logging_outputs( + self, + logging_outputs: List[Dict[str, Any]], + *extra_stats_to_sum, + ignore=False, + ): + if self.task.__class__.logging_outputs_can_be_summed(self.get_criterion()): + return self._fast_stat_sync_sum( + logging_outputs, *extra_stats_to_sum, ignore=ignore + ) + else: + return self._all_gather_list_sync( + logging_outputs, *extra_stats_to_sum, ignore=ignore + ) + + def _all_gather_list_sync( + self, + logging_outputs: List[Dict[str, Any]], + *extra_stats_to_sum, + ignore=False, + ): + """ + Sync logging outputs across workers. all_gather_list_sync is + suitable when logging outputs are complex types. + """ + if self.tpu: + raise NotImplementedError + if ignore: + logging_outputs = [] + results = list( + zip( + *distributed_utils.all_gather_list( + [logging_outputs] + list(extra_stats_to_sum), + max_size=getattr(self.cfg.common, "all_gather_list_size", 16384), + group=self.data_parallel_process_group, + ) + ) + ) + logging_outputs, extra_stats_to_sum = results[0], results[1:] + logging_outputs = list(chain.from_iterable(logging_outputs)) + extra_stats_to_sum = [sum(s) for s in extra_stats_to_sum] + return logging_outputs, extra_stats_to_sum + + def _fast_stat_sync_sum( + self, + logging_outputs: List[Dict[str, Any]], + *extra_stats_to_sum, + ignore=False, + ): + """ + Sync logging outputs across workers. fast_stat_sync_sum is + faster than all_gather_list_sync, but is only suitable when + logging outputs are scalars and can be summed. Note that + *logging_outputs* cannot contain any nested dicts/lists. + """ + data = {} + for i, stat in enumerate(extra_stats_to_sum): + data["extra_stats_" + str(i)] = stat + if len(logging_outputs) > 0: + log_keys = list(logging_outputs[0].keys()) + for k in log_keys: + if not ignore: + v = sum(log[k] for log in logging_outputs if k in log) + else: + v = logging_outputs[0][k] + v = torch.zeros_like(v) if torch.is_tensor(v) else 0 + data["logging_outputs_" + k] = v + else: + log_keys = None + + data = distributed_utils.all_reduce_dict( + data, device=self.device, group=self.data_parallel_process_group + ) + + extra_stats_to_sum = [ + data["extra_stats_" + str(i)] for i in range(len(extra_stats_to_sum)) + ] + if log_keys is not None: + logging_outputs = [{k: data["logging_outputs_" + k] for k in log_keys}] + else: + logging_outputs = [] + return logging_outputs, extra_stats_to_sum + + def _check_grad_norms(self, grad_norm): + """Check that grad norms are consistent across workers.""" + if self._grad_norm_buf is not None: + self._grad_norm_buf.zero_() + self._grad_norm_buf[self.data_parallel_rank] = grad_norm + distributed_utils.all_reduce( + self._grad_norm_buf, group=self.data_parallel_process_group + ) + + def is_consistent(tensor): + max_abs_diff = torch.max(torch.abs(tensor - tensor[0])) + return ( + ( + torch.isfinite(tensor).all() + and (max_abs_diff / (tensor[0] + 1e-6) < 1e-6).all() + ) + or (self.cfg.common.amp and not torch.isfinite(tensor).all()) + # in case of amp non-finite grads are fine + ) + + if not is_consistent(self._grad_norm_buf): + pretty_detail = "\n".join( + "rank {:3d} = {:.8f}".format(r, n) + for r, n in enumerate(self._grad_norm_buf.tolist()) + ) + error_detail = "grad_norm across the workers:\n{}\n".format( + pretty_detail + ) + # use FloatingPointError to trigger NanDetector + raise FloatingPointError( + "Fatal error: gradients are inconsistent between workers. " + "Try --ddp-backend=legacy_ddp. " + "Or are you mixing up different generation of GPUs in training?" + + "\n" + + "-" * 80 + + "\n{}\n".format(error_detail) + + "-" * 80 + ) + + def _reduce_and_log_stats(self, logging_outputs, sample_size, grad_norm=None): + if grad_norm is not None and ( + not torch.is_tensor(grad_norm) or torch.isfinite(grad_norm) + ): + metrics.log_speed("ups", 1.0, priority=100, round=2) + metrics.log_scalar("gnorm", grad_norm, priority=400, round=3) + if self.cfg.optimization.clip_norm > 0: + metrics.log_scalar( + "clip", + torch.where( + grad_norm > self.cfg.optimization.clip_norm, + grad_norm.new_tensor(100), + grad_norm.new_tensor(0), + ), + priority=500, + round=1, + ) + + with metrics.aggregate() as agg: + if logging_outputs is not None: + self.task.reduce_metrics(logging_outputs, self.get_criterion()) + del logging_outputs + + # extra warning for criterions that don't properly log a loss value + if "loss" not in agg: + if "loss" not in self._warn_once: + self._warn_once.add("loss") + logger.warning( + "Criterion.reduce_metrics did not log a 'loss' value, " + "which may break some functionality" + ) + metrics.log_scalar("loss", -1) + + # support legacy interface + if self.tpu: + logging_output = {} + else: + logging_output = agg.get_smoothed_values() + logging_output["sample_size"] = sample_size + for key_to_delete in ["ppl", "wps", "wpb", "bsz"]: + if key_to_delete in logging_output: + del logging_output[key_to_delete] + return logging_output + + def _check_xla_compilation(self): + import torch_xla.debug.metrics as met + + compile_stats = met.metric_data("CompileTime") + if compile_stats is None: + return + num_xla_compiles = compile_stats[0] + if num_xla_compiles > self._num_xla_compiles: + logger.warning( + "XLA compilation detected on device #{}; too many of these can lead " + "to slow training, but we expect a few in the beginning".format( + self.cfg.distributed_training.distributed_rank + ) + ) + self._num_xla_compiles = num_xla_compiles + + def _xla_markstep_and_send_to_cpu(self, data=None): + import torch_xla.core.xla_model as xm + + xm.mark_step() + if data is not None: + from fairseq.utils import xla_device_to_cpu + + return xla_device_to_cpu(data) + + +def _catalog_shared_params(module, memo=None, prefix=""): + if memo is None: + first_call = True + memo = {} + else: + first_call = False + for name, param in module._parameters.items(): + param_prefix = prefix + ("." if prefix else "") + name + if param not in memo: + memo[param] = [] + memo[param].append(param_prefix) + for name, m in module._modules.items(): + if m is None: + continue + submodule_prefix = prefix + ("." if prefix else "") + name + _catalog_shared_params(m, memo, submodule_prefix) + if first_call: + return [x for x in memo.values() if len(x) > 1] + + +def _get_module_by_path(module, path): + path = path.split(".") + for name in path: + module = getattr(module, name) + return module + + +def _set_module_by_path(module, path, value): + path = path.split(".") + for name in path[:-1]: + module = getattr(module, name) + setattr(module, path[-1], value) diff --git a/PyTorch/NLP/new-Transformer/fairseq/utils.py b/PyTorch/NLP/new-Transformer/fairseq/utils.py new file mode 100644 index 00000000..4852f488 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/utils.py @@ -0,0 +1,842 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import argparse +import collections +import contextlib +import copy +import importlib +import logging +import os +import sys +import warnings +from itertools import accumulate +from typing import TYPE_CHECKING, Callable, Dict, List, Optional + +import torch +import torch.nn.functional as F +from torch import Tensor + +if TYPE_CHECKING: + from fairseq.modules.multihead_attention import MultiheadAttention + +try: + from amp_C import multi_tensor_l2norm + + multi_tensor_l2norm_available = True +except ImportError: + multi_tensor_l2norm_available = False + +try: + import torch_xla.core.xla_model as xm +except ImportError: + xm = None + + +logger = logging.getLogger(__name__) + + +MANIFOLD_PATH_SEP = "|" + + +class FileContentsAction(argparse.Action): + def __init__(self, option_strings, dest, nargs=None, **kwargs): + if nargs is not None: + raise ValueError("nargs not allowed") + super(FileContentsAction, self).__init__(option_strings, dest, **kwargs) + + def __call__(self, parser, namespace, values, option_string=None): + from fairseq.file_io import PathManager + + if PathManager.isfile(values): + with PathManager.open(values) as f: + argument = f.read().strip() + else: + argument = values + setattr(namespace, self.dest, argument) + + +def split_paths(paths: str, separator=os.pathsep) -> List[str]: + return ( + paths.split(separator) if "://" not in paths else paths.split(MANIFOLD_PATH_SEP) + ) + + +def load_ensemble_for_inference(filenames, task, model_arg_overrides=None): + from fairseq import checkpoint_utils + + deprecation_warning( + "utils.load_ensemble_for_inference is deprecated. " + "Please use checkpoint_utils.load_model_ensemble instead." + ) + return checkpoint_utils.load_model_ensemble( + filenames, arg_overrides=model_arg_overrides, task=task + ) + + +def apply_to_sample(f, sample): + if hasattr(sample, "__len__") and len(sample) == 0: + return {} + + def _apply(x): + if torch.is_tensor(x): + return f(x) + elif isinstance(x, collections.OrderedDict): + # OrderedDict has attributes that needs to be preserved + od = collections.OrderedDict( + (key, _apply(value)) for key, value in x.items() + ) + od.__dict__ = x.__dict__ + return od + elif isinstance(x, dict): + return {key: _apply(value) for key, value in x.items()} + elif isinstance(x, list): + return [_apply(x) for x in x] + elif isinstance(x, tuple): + return tuple(_apply(x) for x in x) + elif isinstance(x, set): + return {_apply(x) for x in x} + else: + return x + + return _apply(sample) + + +def move_to_cuda(sample, device=None): + device = device or torch.cuda.current_device() + + def _move_to_cuda(tensor): + # non_blocking is ignored if tensor is not pinned, so we can always set + # to True (see github.com/PyTorchLightning/pytorch-lightning/issues/620) + return tensor.to(device=device, non_blocking=True) + + return apply_to_sample(_move_to_cuda, sample) + + +def move_to_cpu(sample): + def _move_to_cpu(tensor): + # PyTorch has poor support for half tensors (float16) on CPU. + # Move any such tensors to float32. + if tensor.dtype in {torch.bfloat16, torch.float16}: + tensor = tensor.to(dtype=torch.float32) + return tensor.cpu() + + return apply_to_sample(_move_to_cpu, sample) + + +def move_to_tpu(sample): + + import torch_xla.core.xla_model as xm + + device = xm.xla_device() + + def _move_to_tpu(tensor): + return tensor.to(device) + + return apply_to_sample(_move_to_tpu, sample) + + +def get_incremental_state( + module: "MultiheadAttention", + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]], + key: str, +) -> Optional[Dict[str, Optional[Tensor]]]: + """Helper for getting incremental state for an nn.Module.""" + return module.get_incremental_state(incremental_state, key) + + +def set_incremental_state( + module: "MultiheadAttention", + incremental_state: Optional[Dict[str, Dict[str, Optional[Tensor]]]], + key: str, + value: Dict[str, Optional[Tensor]], +) -> Optional[Dict[str, Dict[str, Optional[Tensor]]]]: + """Helper for setting incremental state for an nn.Module.""" + if incremental_state is not None: + result = module.set_incremental_state(incremental_state, key, value) + if result is not None: + incremental_state = result + return incremental_state + + +def load_align_dict(replace_unk): + if replace_unk is None: + align_dict = None + elif isinstance(replace_unk, str) and len(replace_unk) > 0: + # Load alignment dictionary for unknown word replacement if it was passed as an argument. + align_dict = {} + with open(replace_unk, "r") as f: + for line in f: + cols = line.split() + align_dict[cols[0]] = cols[1] + else: + # No alignment dictionary provided but we still want to perform unknown word replacement by copying the + # original source word. + align_dict = {} + return align_dict + + +def print_embed_overlap(embed_dict, vocab_dict): + embed_keys = set(embed_dict.keys()) + vocab_keys = set(vocab_dict.symbols) + overlap = len(embed_keys & vocab_keys) + logger.info("found {}/{} types in embedding file".format(overlap, len(vocab_dict))) + + +def parse_embedding(embed_path): + """Parse embedding text file into a dictionary of word and embedding tensors. + + The first line can have vocabulary size and dimension. The following lines + should contain word and embedding separated by spaces. + + Example: + 2 5 + the -0.0230 -0.0264 0.0287 0.0171 0.1403 + at -0.0395 -0.1286 0.0275 0.0254 -0.0932 + """ + embed_dict = {} + with open(embed_path) as f_embed: + next(f_embed) # skip header + for line in f_embed: + pieces = line.rstrip().split(" ") + embed_dict[pieces[0]] = torch.Tensor( + [float(weight) for weight in pieces[1:]] + ) + return embed_dict + + +def load_embedding(embed_dict, vocab, embedding): + for idx in range(len(vocab)): + token = vocab[idx] + if token in embed_dict: + embedding.weight.data[idx] = embed_dict[token] + return embedding + + +def replace_unk(hypo_str, src_str, alignment, align_dict, unk): + from fairseq import tokenizer + + # Tokens are strings here + hypo_tokens = tokenizer.tokenize_line(hypo_str) + # TODO: Very rare cases where the replacement is '' should be handled gracefully + src_tokens = tokenizer.tokenize_line(src_str) + [""] + for i, ht in enumerate(hypo_tokens): + if ht == unk: + src_token = src_tokens[alignment[i]] + # Either take the corresponding value in the aligned dictionary or just copy the original value. + hypo_tokens[i] = align_dict.get(src_token, src_token) + return " ".join(hypo_tokens) + + +def post_process_prediction( + hypo_tokens, + src_str, + alignment, + align_dict, + tgt_dict, + remove_bpe=None, + extra_symbols_to_ignore=None, +): + hypo_str = tgt_dict.string( + hypo_tokens, remove_bpe, extra_symbols_to_ignore=extra_symbols_to_ignore + ) + if align_dict is not None: + hypo_str = replace_unk( + hypo_str, src_str, alignment, align_dict, tgt_dict.unk_string() + ) + if align_dict is not None or remove_bpe is not None: + # Convert back to tokens for evaluating with unk replacement or without BPE + # Note that the dictionary can be modified inside the method. + hypo_tokens = tgt_dict.encode_line(hypo_str, add_if_not_exist=True) + return hypo_tokens, hypo_str, alignment + + +def make_positions(tensor, padding_idx: int, onnx_trace: bool = False): + """Replace non-padding symbols with their position numbers. + + Position numbers begin at padding_idx+1. Padding symbols are ignored. + """ + # The series of casts and type-conversions here are carefully + # balanced to both work with ONNX export and XLA. In particular XLA + # prefers ints, cumsum defaults to output longs, and ONNX doesn't know + # how to handle the dtype kwarg in cumsum. + mask = tensor.ne(padding_idx).int() + return (torch.cumsum(mask, dim=1).type_as(mask) * mask).long() + padding_idx + + +def strip_pad(tensor, pad): + return tensor[tensor.ne(pad)] + + +def buffered_arange(max): + if not hasattr(buffered_arange, "buf"): + buffered_arange.buf = torch.LongTensor() + if max > buffered_arange.buf.numel(): + buffered_arange.buf.resize_(max) + torch.arange(max, out=buffered_arange.buf) + return buffered_arange.buf[:max] + + +def convert_padding_direction( + src_tokens, padding_idx, right_to_left: bool = False, left_to_right: bool = False +): + assert right_to_left ^ left_to_right + pad_mask = src_tokens.eq(padding_idx) + if not pad_mask.any(): + # no padding, return early + return src_tokens + if left_to_right and not pad_mask[:, 0].any(): + # already right padded + return src_tokens + if right_to_left and not pad_mask[:, -1].any(): + # already left padded + return src_tokens + max_len = src_tokens.size(1) + buffered = torch.empty(0).long() + if max_len > 0: + torch.arange(max_len, out=buffered) + range = buffered.type_as(src_tokens).expand_as(src_tokens) + num_pads = pad_mask.long().sum(dim=1, keepdim=True) + if right_to_left: + index = torch.remainder(range - num_pads, max_len) + else: + index = torch.remainder(range + num_pads, max_len) + return src_tokens.gather(1, index) + + +def item(tensor): + # tpu-comment: making this a no-op for xla devices. + if torch.is_tensor(tensor) and tensor.device.type == "xla": + return tensor.detach() + if hasattr(tensor, "item"): + return tensor.item() + if hasattr(tensor, "__getitem__"): + return tensor[0] + return tensor + + +def multi_tensor_total_norm(grads, chunk_size=2048 * 32) -> torch.Tensor: + per_device_grads = {} + norms = [] + for grad in grads: + device = grad.device + cur_device_grads = per_device_grads.get(device) + if cur_device_grads is None: + cur_device_grads = [] + per_device_grads[device] = cur_device_grads + cur_device_grads.append(grad) + for device in per_device_grads.keys(): + cur_device_grads = per_device_grads[device] + if device.type == "cuda": + # TODO(msb) return has_inf + has_inf = torch.zeros((1, 1), dtype=torch.int, device=device) + with torch.cuda.device(device): + norm = multi_tensor_l2norm( + chunk_size, has_inf, [cur_device_grads], False + ) + norms.append(norm[0].to(torch.cuda.current_device())) + else: + norms += [torch.norm(g, p=2, dtype=torch.float32) for g in cur_device_grads] + total_norm = torch.norm(torch.stack(norms)) + return total_norm + + +@torch.no_grad() +def clip_grad_norm_(params, max_norm, aggregate_norm_fn=None) -> torch.Tensor: + def grad_exists(p): + return p is not None and getattr(p, "grad", None) is not None + + if isinstance(params, torch.Tensor): + params = [params] + params = list(params) + grads = [ + p.grad.detach() for p in params if grad_exists(p) and not hasattr(p, "expert") + ] + expert_grads = [ + p.grad.detach() for p in params if grad_exists(p) and hasattr(p, "expert") + ] + + if len(grads) == 0: + if len(params) > 0: + return params[0].new_tensor(0.0) + else: + return torch.tensor(0.0) + + if len(grads) == 1: + total_norm = torch.norm(grads[0], p=2, dtype=torch.float32) + else: + if multi_tensor_l2norm_available: + total_norm = multi_tensor_total_norm(grads) + else: + if torch.cuda.is_available(): + warnings.warn( + "amp_C fused kernels unavailable, disabling multi_tensor_l2norm; " + "you may get better performance by installing NVIDIA's apex library" + ) + device = torch.cuda.current_device() + elif grads[0].device.type == "xla": + device = grads[0].device + else: + device = torch.device("cpu") + total_norm = torch.norm( + torch.stack( + [torch.norm(g, p=2, dtype=torch.float32).to(device) for g in grads] + ) + ) + + if aggregate_norm_fn is not None: + total_norm = aggregate_norm_fn(total_norm) + + if max_norm > 0: + max_norm = float(max_norm) + clip_coef = (max_norm / (total_norm + 1e-6)).clamp_(max=1) + for g in grads + expert_grads: + g.mul_(clip_coef) + return total_norm + + +def fill_with_neg_inf(t): + """FP16-compatible function that fills a tensor with -inf.""" + return t.float().fill_(float("-inf")).type_as(t) + + +def _match_types(arg1, arg2): + """Convert the numerical argument to the same type as the other argument""" + + def upgrade(arg_number, arg_structure): + if isinstance(arg_structure, tuple): + return tuple([arg_number] * len(arg_structure)) + elif isinstance(arg_structure, dict): + arg = copy.deepcopy(arg_structure) + for k in arg: + arg[k] = upgrade(arg_number, arg_structure[k]) + return arg + else: + return arg_number + + if isinstance(arg1, float) or isinstance(arg1, int): + return upgrade(arg1, arg2), arg2 + elif isinstance(arg2, float) or isinstance(arg2, int): + return arg1, upgrade(arg2, arg1) + + return arg1, arg2 + + +def resolve_max_positions(*args): + """Resolve max position constraints from multiple sources.""" + + def map_value_update(d1, d2): + updated_value = copy.deepcopy(d1) + for key in d2: + if key not in updated_value: + updated_value[key] = d2[key] + else: + updated_value[key] = min(d1[key], d2[key]) + return updated_value + + def nullsafe_min(l): + minim = None + for item in l: + if minim is None: + minim = item + elif item is not None and item < minim: + minim = item + return minim + + max_positions = None + for arg in args: + if max_positions is None: + max_positions = arg + elif arg is not None: + max_positions, arg = _match_types(max_positions, arg) + if isinstance(arg, float) or isinstance(arg, int): + max_positions = min(max_positions, arg) + elif isinstance(arg, dict): + max_positions = map_value_update(max_positions, arg) + else: + max_positions = tuple(map(nullsafe_min, zip(max_positions, arg))) + + return max_positions + + +def import_user_module(args): + module_path = getattr(args, "user_dir", None) + if module_path is not None: + module_path = os.path.abspath(args.user_dir) + if not os.path.exists(module_path) and not os.path.isfile( + os.path.dirname(module_path) + ): + fairseq_rel_path = os.path.join(os.path.dirname(__file__), args.user_dir) + if os.path.exists(fairseq_rel_path): + module_path = fairseq_rel_path + else: + fairseq_rel_path = os.path.join( + os.path.dirname(__file__), "..", args.user_dir + ) + if os.path.exists(fairseq_rel_path): + module_path = fairseq_rel_path + else: + raise FileNotFoundError(module_path) + + # ensure that user modules are only imported once + import_user_module.memo = getattr(import_user_module, "memo", set()) + if module_path not in import_user_module.memo: + import_user_module.memo.add(module_path) + + module_parent, module_name = os.path.split(module_path) + if module_name not in sys.modules: + sys.path.insert(0, module_parent) + importlib.import_module(module_name) + + tasks_path = os.path.join(module_path, "tasks") + if os.path.exists(tasks_path): + from fairseq.tasks import import_tasks + + import_tasks(tasks_path, f"{module_name}.tasks") + + models_path = os.path.join(module_path, "models") + if os.path.exists(models_path): + from fairseq.models import import_models + + import_models(models_path, f"{module_name}.models") + elif module_path in sys.modules[module_name].__path__: + logger.info(f"--user-dir={module_path} has already been imported.") + else: + raise ImportError( + "Failed to import --user-dir={} because the corresponding module name " + "({}) is not globally unique. Please rename the directory to " + "something unique and try again.".format(module_path, module_name) + ) + + +def softmax(x, dim: int, onnx_trace: bool = False): + if onnx_trace: + return F.softmax(x.float(), dim=dim) + else: + return F.softmax(x, dim=dim, dtype=torch.float32) + + +def log_softmax(x, dim: int, onnx_trace: bool = False): + if onnx_trace: + return F.log_softmax(x.float(), dim=dim) + else: + return F.log_softmax(x, dim=dim, dtype=torch.float32) + + +def get_perplexity(loss, round=2, base=2): + from fairseq.logging.meters import safe_round + + if loss is None: + return 0.0 + try: + return safe_round(base**loss, round) + except OverflowError: + return float("inf") + + +def deprecation_warning(message, stacklevel=3): + # don't use DeprecationWarning, since it's ignored by default + warnings.warn(message, stacklevel=stacklevel) + + +def relu_squared(x: torch.Tensor): + return F.relu(x).pow(2) + + +def get_activation_fn(activation: str) -> Callable: + """Returns the activation function corresponding to `activation`""" + from fairseq.modules import gelu, gelu_accurate + + if activation == "relu": + return F.relu + elif activation == "relu_squared": + return relu_squared + elif activation == "gelu": + return gelu + elif activation == "gelu_fast": + deprecation_warning( + "--activation-fn=gelu_fast has been renamed to gelu_accurate" + ) + return gelu_accurate + elif activation == "gelu_accurate": + return gelu_accurate + elif activation == "tanh": + return torch.tanh + elif activation == "linear": + return lambda x: x + elif activation == "swish": + return torch.nn.SiLU + else: + raise RuntimeError("--activation-fn {} not supported".format(activation)) + + +def get_available_activation_fns() -> List: + return [ + "relu", + "gelu", + "gelu_fast", # deprecated + "gelu_accurate", + "tanh", + "linear", + ] + + +@contextlib.contextmanager +def model_eval(model): + is_training = model.training + model.eval() + yield + model.train(is_training) + + +def has_parameters(module): + try: + next(module.parameters()) + return True + except StopIteration: + return False + + +def get_rng_state(): + state = {"torch_rng_state": torch.get_rng_state()} + if xm is not None: + state["xla_rng_state"] = xm.get_rng_state() + if torch.cuda.is_available(): + state["cuda_rng_state"] = torch.cuda.get_rng_state() + return state + + +def set_rng_state(state): + torch.set_rng_state(state["torch_rng_state"]) + if xm is not None: + xm.set_rng_state(state["xla_rng_state"]) + if torch.cuda.is_available(): + torch.cuda.set_rng_state(state["cuda_rng_state"]) + + +class set_torch_seed(object): + def __init__(self, seed): + assert isinstance(seed, int) + self.rng_state = get_rng_state() + + torch.manual_seed(seed) + if xm is not None: + xm.set_rng_state(seed) + if torch.cuda.is_available(): + torch.cuda.manual_seed(seed) + + def __enter__(self): + return self + + def __exit__(self, *exc): + set_rng_state(self.rng_state) + + +def parse_alignment(line): + """ + Parses a single line from the alingment file. + + Args: + line (str): String containing the alignment of the format: + - - .. + -. All indices are 0 indexed. + + Returns: + torch.IntTensor: packed alignments of shape (2 * m). + """ + alignments = line.strip().split() + parsed_alignment = torch.IntTensor(2 * len(alignments)) + for idx, alignment in enumerate(alignments): + src_idx, tgt_idx = alignment.split("-") + parsed_alignment[2 * idx] = int(src_idx) + parsed_alignment[2 * idx + 1] = int(tgt_idx) + return parsed_alignment + + +def get_token_to_word_mapping(tokens, exclude_list): + n = len(tokens) + word_start = [int(token not in exclude_list) for token in tokens] + word_idx = list(accumulate(word_start)) + token_to_word = {i: word_idx[i] for i in range(n)} + return token_to_word + + +def extract_hard_alignment(attn, src_sent, tgt_sent, pad, eos): + tgt_valid = ( + ((tgt_sent != pad) & (tgt_sent != eos)).nonzero(as_tuple=False).squeeze(dim=-1) + ) + src_invalid = ( + ((src_sent == pad) | (src_sent == eos)).nonzero(as_tuple=False).squeeze(dim=-1) + ) + src_token_to_word = get_token_to_word_mapping(src_sent, [eos, pad]) + tgt_token_to_word = get_token_to_word_mapping(tgt_sent, [eos, pad]) + alignment = [] + if len(tgt_valid) != 0 and len(src_invalid) < len(src_sent): + attn_valid = attn[tgt_valid] + attn_valid[:, src_invalid] = float("-inf") + _, src_indices = attn_valid.max(dim=1) + for tgt_idx, src_idx in zip(tgt_valid, src_indices): + alignment.append( + ( + src_token_to_word[src_idx.item()] - 1, + tgt_token_to_word[tgt_idx.item()] - 1, + ) + ) + return alignment + + +def extract_soft_alignment(attn, src_sent, tgt_sent, pad, eos): + tgt_valid = ((tgt_sent != pad)).nonzero(as_tuple=False) + src_valid = ((src_sent != pad)).nonzero(as_tuple=False).squeeze(dim=-1) + alignment = [] + if len(tgt_valid) != 0 and len(src_valid) != 0: + attn_valid = attn[tgt_valid, src_valid] + alignment = [ + ["{:.6f}".format(p) for p in src_probs.tolist()] for src_probs in attn_valid + ] + return alignment + + +def new_arange(x, *size): + """ + Return a Tensor of `size` filled with a range function on the device of x. + If size is empty, using the size of the variable x. + """ + if len(size) == 0: + size = x.size() + return torch.arange(size[-1], device=x.device).expand(*size).contiguous() + + +def get_tpu_device(): + return xm.xla_device() + + +def tpu_data_loader(itr): + import torch_xla.core.xla_model as xm + import torch_xla.distributed.parallel_loader as pl + + from fairseq.data import iterators + + xm.rendezvous("tpu_data_loader") # wait for all workers + xm.mark_step() + device = xm.xla_device() + return iterators.CountingIterator( + pl.ParallelLoader(itr, [device]).per_device_loader(device), + start=getattr(itr, "n", 0), + total=len(itr), + ) + + +def is_xla_tensor(tensor): + return torch.is_tensor(tensor) and tensor.device.type == "xla" + + +def index_put(tensor, indices, value): + if is_xla_tensor(tensor): + for _ in range(indices.dim(), tensor.dim()): + indices = indices.unsqueeze(-1) + if indices.size(-1) < tensor.size(-1): + indices = indices.expand_as(tensor) + tensor = torch.mul(tensor, ~indices) + torch.mul(value, indices) + else: + tensor[indices] = value + return tensor + + +def xla_device_to_cpu(dat): + import torch_xla.core.xla_model as xm + + return xm._maybe_convert_to_cpu(dat) + + +class CudaEnvironment(object): + def __init__(self): + cur_device = torch.cuda.current_device() + prop = torch.cuda.get_device_properties("cuda:{}".format(cur_device)) + self.name = prop.name + self.major = prop.major + self.minor = prop.minor + self.total_memory_in_GB = prop.total_memory / 1024 / 1024 / 1024 + + @staticmethod + def pretty_print_cuda_env_list(cuda_env_list): + """ + Given a list of CudaEnviorments, pretty print them + """ + num_workers = len(cuda_env_list) + center = "CUDA enviroments for all {} workers".format(num_workers) + banner_len = 40 - len(center) // 2 + first_line = "*" * banner_len + center + "*" * banner_len + logger.info(first_line) + for r, env in enumerate(cuda_env_list): + logger.info( + "rank {:3d}: ".format(r) + + "capabilities = {:2d}.{:<2d} ; ".format(env.major, env.minor) + + "total memory = {:.3f} GB ; ".format(env.total_memory_in_GB) + + "name = {:40s}".format(env.name) + ) + logger.info(first_line) + + +def csv_str_list(x): + return x.split(",") + + +def eval_str_list(x, type=float): + if x is None: + return None + if isinstance(x, str): + x = eval(x) + try: + return list(map(type, x)) + except TypeError: + return [type(x)] + + +def eval_str_dict(x, type=dict): + if x is None: + return None + if isinstance(x, str): + x = eval(x) + return x + + +def eval_bool(x, default=False): + if x is None: + return default + try: + return bool(eval(x)) + except TypeError: + return default + + +def reset_logging(): + root = logging.getLogger() + for handler in root.handlers: + root.removeHandler(handler) + root.setLevel(os.environ.get("LOGLEVEL", "INFO").upper()) + handler = logging.StreamHandler(sys.stdout) + handler.setFormatter( + logging.Formatter( + fmt="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + ) + ) + root.addHandler(handler) + + +def safe_getattr(obj, k, default=None): + """Returns obj[k] if it exists and is not None, otherwise returns default.""" + from omegaconf import OmegaConf + + if OmegaConf.is_config(obj): + return obj[k] if k in obj and obj[k] is not None else default + + return getattr(obj, k, default) + + +def safe_hasattr(obj, k): + """Returns True if the given key exists and is not None.""" + return getattr(obj, k, None) is not None diff --git a/PyTorch/NLP/new-Transformer/fairseq/version.txt b/PyTorch/NLP/new-Transformer/fairseq/version.txt new file mode 100644 index 00000000..d9df1bbc --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq/version.txt @@ -0,0 +1 @@ +0.11.0 diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/__init__.py b/PyTorch/NLP/new-Transformer/fairseq_cli/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/eval_lm.py b/PyTorch/NLP/new-Transformer/fairseq_cli/eval_lm.py new file mode 100644 index 00000000..dbd1450a --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq_cli/eval_lm.py @@ -0,0 +1,347 @@ +#!/usr/bin/env python3 -u +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +""" +Evaluate the perplexity of a trained language model. +""" + +import logging +import math +import os +import sys +from argparse import Namespace +from typing import Iterable, List, Optional + +import torch +from omegaconf import DictConfig + +import fairseq +from fairseq import checkpoint_utils, distributed_utils, options, tasks, utils +from fairseq.dataclass.utils import convert_namespace_to_omegaconf +from fairseq.logging import progress_bar +from fairseq.logging.meters import StopwatchMeter +from fairseq.sequence_scorer import SequenceScorer + +logging.basicConfig( + format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + level=os.environ.get("LOGLEVEL", "INFO").upper(), + stream=sys.stdout, +) +logger = logging.getLogger("fairseq_cli.eval_lm") + + +def eval_lm( + models: List[fairseq.models.FairseqModel], + source_dictionary: fairseq.data.Dictionary, + batch_iterator: Iterable, + post_process: Optional[str] = None, + output_word_probs: bool = False, + output_word_stats: bool = False, + target_dictionary: Optional[fairseq.data.Dictionary] = None, + softmax_batch: int = 0, + remove_bos_token: bool = False, + device: Optional[torch.device] = None, +): + """ + Args: + models (List[~fairseq.models.FairseqModel]): list of models to + evaluate. Models are essentially `nn.Module` instances, but + must be compatible with fairseq's `SequenceScorer`. + source_dictionary (~fairseq.data.Dictionary): dictionary for + applying any relevant post processing or outputing word + probs/stats. + batch_iterator (Iterable): yield batches of data + post_process (Optional[str]): post-process text by removing BPE, + letter segmentation, etc. Valid options can be found in + fairseq.data.utils.post_process, although not all options + are implemented here. + output_word_probs (Optional[bool]): output words and their + predicted log probabilities + output_word_stats (Optional[bool]): output word statistics such + as word count and average probability + target_dictionary (Optional[~fairseq.data.Dictionary]): output + dictionary (defaults to *source_dictionary*) + softmax_batch (Optional[bool]): if BxT is more than this, will + batch the softmax over vocab to this amount of tokens, in + order to fit into GPU memory + remove_bos_token (Optional[bool]): if True, confirm that the + first token is the beginning-of-sentence symbol (according + to the relevant dictionary) and remove it from the output + device (Optional[torch.device]): device to use for evaluation + (defaults to device of first model parameter) + """ + if target_dictionary is None: + target_dictionary = source_dictionary + if device is None: + device = next(models[0].parameters()).device + + gen_timer = StopwatchMeter() + scorer = SequenceScorer(target_dictionary, softmax_batch) + + score_sum = 0.0 + count = 0 + + if post_process is not None: + if post_process in {"subword_nmt", "@@ "}: + bpe_cont = post_process.rstrip() + bpe_toks = { + i + for i in range(len(source_dictionary)) + if source_dictionary[i].endswith(bpe_cont) + } + else: + raise NotImplementedError( + f"--post-process={post_process} is not implemented" + ) + bpe_len = len(bpe_cont) + else: + bpe_toks = None + bpe_len = 0 + + word_stats = dict() + + for sample in batch_iterator: + if "net_input" not in sample: + continue + + sample = utils.move_to_cuda(sample, device=device) + + gen_timer.start() + hypos = scorer.generate(models, sample) + gen_timer.stop(sample["ntokens"]) + + for i, hypos_i in enumerate(hypos): + hypo = hypos_i[0] + sample_id = sample["id"][i] + + tokens = hypo["tokens"] + tgt_len = tokens.numel() + pos_scores = hypo["positional_scores"].float() + + if remove_bos_token: + assert hypo["tokens"][0].item() == target_dictionary.bos() + tokens = tokens[1:] + pos_scores = pos_scores[1:] + + skipped_toks = 0 + if bpe_toks is not None: + for i in range(tgt_len - 1): + if tokens[i].item() in bpe_toks: + skipped_toks += 1 + pos_scores[i + 1] += pos_scores[i] + pos_scores[i] = 0 + + inf_scores = pos_scores.eq(float("inf")) | pos_scores.eq(float("-inf")) + if inf_scores.any(): + logger.info( + "skipping tokens with inf scores:", + target_dictionary.string(tokens[inf_scores.nonzero()]), + ) + pos_scores = pos_scores[(~inf_scores).nonzero()] + score_sum += pos_scores.sum().cpu() + count += pos_scores.numel() - skipped_toks + + if output_word_probs or output_word_stats: + w = "" + word_prob = [] + is_bpe = False + for i in range(len(tokens)): + w_ind = tokens[i].item() + w += source_dictionary[w_ind] + if bpe_toks is not None and w_ind in bpe_toks: + w = w[:-bpe_len] + is_bpe = True + else: + word_prob.append((w, pos_scores[i].item())) + + next_prob = None + ind = i + 1 + while ind < len(tokens): + if pos_scores[ind].item() != 0: + next_prob = pos_scores[ind] + break + ind += 1 + + word_stats.setdefault(w, WordStat(w, is_bpe)).add( + pos_scores[i].item(), next_prob + ) + is_bpe = False + w = "" + if output_word_probs: + logger.info( + str(int(sample_id)) + + " " + + ( + "\t".join( + "{} [{:2f}]".format(x[0], x[1]) for x in word_prob + ) + ) + ) + + avg_nll_loss = ( + -score_sum / count / math.log(2) if count > 0 else 0 + ) # convert to base 2 + logger.info( + "Evaluated {:,} tokens in {:.1f}s ({:.2f} tokens/s)".format( + gen_timer.n, gen_timer.sum, 1.0 / gen_timer.avg if gen_timer.avg > 0 else 0 + ) + ) + + if output_word_stats: + for ws in sorted(word_stats.values(), key=lambda x: x.count, reverse=True): + logger.info(ws) + + return { + "loss": avg_nll_loss, + "perplexity": 2**avg_nll_loss, + } + + +class WordStat(object): + def __init__(self, word, is_bpe): + self.word = word + self.is_bpe = is_bpe + self.log_prob = 0 + self.next_word_prob = 0 + self.count = 0 + self.missing_next_words = 0 + + def add(self, log_prob, next_word_prob): + """increments counters for the sum of log probs of current word and next + word (given context ending at current word). Since the next word might be at the end of the example, + or it might be not counted because it is not an ending subword unit, + also keeps track of how many of those we have seen""" + if next_word_prob is not None: + self.next_word_prob += next_word_prob + else: + self.missing_next_words += 1 + self.log_prob += log_prob + self.count += 1 + + def __str__(self): + return "{}\t{}\t{}\t{}\t{}\t{}".format( + self.word, + self.count, + self.log_prob, + self.is_bpe, + self.next_word_prob, + self.count - self.missing_next_words, + ) + + +def main(cfg: DictConfig, **unused_kwargs): + if isinstance(cfg, Namespace): + cfg = convert_namespace_to_omegaconf(cfg) + + utils.import_user_module(cfg.common) + + logger.info(cfg) + + if cfg.eval_lm.context_window > 0: + # reduce tokens per sample by the required context window size + cfg.task.tokens_per_sample -= cfg.eval_lm.context_window + + # Initialize the task using the current *cfg* + task = tasks.setup_task(cfg.task) + + # Load ensemble + logger.info("loading model(s) from {}".format(cfg.common_eval.path)) + models, model_args, task = checkpoint_utils.load_model_ensemble_and_task( + [cfg.common_eval.path], + arg_overrides=eval(cfg.common_eval.model_overrides), + suffix=cfg.checkpoint.checkpoint_suffix, + strict=(cfg.checkpoint.checkpoint_shard_count == 1), + num_shards=cfg.checkpoint.checkpoint_shard_count, + task=task, + ) + + use_fp16 = cfg.common.fp16 + use_cuda = torch.cuda.is_available() and not cfg.common.cpu + if use_cuda: + torch.cuda.set_device(cfg.distributed_training.device_id) + + # Optimize ensemble for generation and set the source and dest dicts on the model + # (required by scorer) + for model in models: + if use_fp16: + model.half() + if use_cuda and not cfg.distributed_training.pipeline_model_parallel: + model.cuda() + model.prepare_for_inference_(cfg) + + assert len(models) > 0 + + logger.info( + "num. model params: {:,}".format(sum(p.numel() for p in models[0].parameters())) + ) + + # Load dataset splits + task.load_dataset(cfg.dataset.gen_subset) + dataset = task.dataset(cfg.dataset.gen_subset) + logger.info( + "{} {} {:,} examples".format( + cfg.task.data, cfg.dataset.gen_subset, len(dataset) + ) + ) + + itr = task.eval_lm_dataloader( + dataset=dataset, + max_tokens=cfg.dataset.max_tokens or 36000, + batch_size=cfg.dataset.batch_size, + max_positions=utils.resolve_max_positions( + *[model.max_positions() for model in models] + ), + num_shards=max( + cfg.dataset.num_shards, + cfg.distributed_training.distributed_world_size, + ), + shard_id=max( + cfg.dataset.shard_id, + cfg.distributed_training.distributed_rank, + ), + num_workers=cfg.dataset.num_workers, + data_buffer_size=cfg.dataset.data_buffer_size, + context_window=cfg.eval_lm.context_window, + ) + + itr = progress_bar.progress_bar( + itr, + log_format=cfg.common.log_format, + log_interval=cfg.common.log_interval, + default_log_format=("tqdm" if not cfg.common.no_progress_bar else "simple"), + ) + + results = eval_lm( + models=models, + source_dictionary=task.source_dictionary, + batch_iterator=itr, + post_process=cfg.common_eval.post_process, + output_word_probs=cfg.eval_lm.output_word_probs, + output_word_stats=cfg.eval_lm.output_word_stats, + target_dictionary=task.target_dictionary, + softmax_batch=cfg.eval_lm.softmax_batch, + remove_bos_token=getattr(cfg.task, "add_bos_token", False), + ) + + logger.info( + "Loss (base 2): {:.4f}, Perplexity: {:.2f}".format( + results["loss"], results["perplexity"] + ) + ) + + return results + + +def cli_main(): + parser = options.get_eval_lm_parser() + args = options.parse_args_and_arch(parser) + + distributed_utils.call_main(convert_namespace_to_omegaconf(args), main) + + +if __name__ == "__main__": + cli_main() diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/generate.py b/PyTorch/NLP/new-Transformer/fairseq_cli/generate.py new file mode 100644 index 00000000..b8757835 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq_cli/generate.py @@ -0,0 +1,417 @@ +#!/usr/bin/env python3 -u +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Translate pre-processed data with a trained model. +""" + +import ast +import logging +import math +import os +import sys +from argparse import Namespace +from itertools import chain + +import numpy as np +import torch +from omegaconf import DictConfig + +from fairseq import checkpoint_utils, options, scoring, tasks, utils +from fairseq.dataclass.utils import convert_namespace_to_omegaconf +from fairseq.logging import progress_bar +from fairseq.logging.meters import StopwatchMeter, TimeMeter + + +def main(cfg: DictConfig): + + if isinstance(cfg, Namespace): + cfg = convert_namespace_to_omegaconf(cfg) + + assert cfg.common_eval.path is not None, "--path required for generation!" + assert ( + not cfg.generation.sampling or cfg.generation.nbest == cfg.generation.beam + ), "--sampling requires --nbest to be equal to --beam" + assert ( + cfg.generation.replace_unk is None or cfg.dataset.dataset_impl == "raw" + ), "--replace-unk requires a raw text dataset (--dataset-impl=raw)" + + if cfg.common_eval.results_path is not None: + os.makedirs(cfg.common_eval.results_path, exist_ok=True) + output_path = os.path.join( + cfg.common_eval.results_path, + "generate-{}.txt".format(cfg.dataset.gen_subset), + ) + with open(output_path, "w", buffering=1, encoding="utf-8") as h: + return _main(cfg, h) + else: + return _main(cfg, sys.stdout) + + +def get_symbols_to_strip_from_output(generator): + if hasattr(generator, "symbols_to_strip_from_output"): + return generator.symbols_to_strip_from_output + else: + return {generator.eos} + + +def _main(cfg: DictConfig, output_file): + logging.basicConfig( + format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + level=os.environ.get("LOGLEVEL", "INFO").upper(), + stream=output_file, + ) + logger = logging.getLogger("fairseq_cli.generate") + + utils.import_user_module(cfg.common) + + if cfg.dataset.max_tokens is None and cfg.dataset.batch_size is None: + cfg.dataset.max_tokens = 12000 + logger.info(cfg) + + # Fix seed for stochastic decoding + if cfg.common.seed is not None and not cfg.generation.no_seed_provided: + np.random.seed(cfg.common.seed) + utils.set_torch_seed(cfg.common.seed) + + use_cuda = torch.cuda.is_available() and not cfg.common.cpu + + # Load dataset splits + task = tasks.setup_task(cfg.task) + + # Set dictionaries + try: + src_dict = getattr(task, "source_dictionary", None) + except NotImplementedError: + src_dict = None + tgt_dict = task.target_dictionary + + overrides = ast.literal_eval(cfg.common_eval.model_overrides) + + # Load ensemble + logger.info("loading model(s) from {}".format(cfg.common_eval.path)) + models, saved_cfg = checkpoint_utils.load_model_ensemble( + utils.split_paths(cfg.common_eval.path), + arg_overrides=overrides, + task=task, + suffix=cfg.checkpoint.checkpoint_suffix, + strict=(cfg.checkpoint.checkpoint_shard_count == 1), + num_shards=cfg.checkpoint.checkpoint_shard_count, + ) + + # loading the dataset should happen after the checkpoint has been loaded so we can give it the saved task config + task.load_dataset(cfg.dataset.gen_subset, task_cfg=saved_cfg.task) + + if cfg.generation.lm_path is not None: + overrides["data"] = cfg.task.data + + try: + lms, _ = checkpoint_utils.load_model_ensemble( + [cfg.generation.lm_path], arg_overrides=overrides, task=None + ) + except: + logger.warning( + f"Failed to load language model! Please make sure that the language model dict is the same " + f"as target dict and is located in the data dir ({cfg.task.data})" + ) + raise + + assert len(lms) == 1 + else: + lms = [None] + + # Optimize ensemble for generation + for model in chain(models, lms): + if model is None: + continue + if cfg.common.fp16: + model.half() + if use_cuda and not cfg.distributed_training.pipeline_model_parallel: + model.cuda() + model.prepare_for_inference_(cfg) + + # Load alignment dictionary for unknown word replacement + # (None if no unknown word replacement, empty if no path to align dictionary) + align_dict = utils.load_align_dict(cfg.generation.replace_unk) + + # Load dataset (possibly sharded) + itr = task.get_batch_iterator( + dataset=task.dataset(cfg.dataset.gen_subset), + max_tokens=cfg.dataset.max_tokens, + max_sentences=cfg.dataset.batch_size, + max_positions=utils.resolve_max_positions( + task.max_positions(), *[m.max_positions() for m in models] + ), + ignore_invalid_inputs=cfg.dataset.skip_invalid_size_inputs_valid_test, + required_batch_size_multiple=cfg.dataset.required_batch_size_multiple, + seed=cfg.common.seed, + num_shards=cfg.distributed_training.distributed_world_size, + shard_id=cfg.distributed_training.distributed_rank, + num_workers=cfg.dataset.num_workers, + data_buffer_size=cfg.dataset.data_buffer_size, + ).next_epoch_itr(shuffle=False) + progress = progress_bar.progress_bar( + itr, + log_format=cfg.common.log_format, + log_interval=cfg.common.log_interval, + default_log_format=("tqdm" if not cfg.common.no_progress_bar else "simple"), + ) + + # Initialize generator + gen_timer = StopwatchMeter() + + extra_gen_cls_kwargs = {"lm_model": lms[0], "lm_weight": cfg.generation.lm_weight} + generator = task.build_generator( + models, cfg.generation, extra_gen_cls_kwargs=extra_gen_cls_kwargs + ) + + # Handle tokenization and BPE + tokenizer = task.build_tokenizer(cfg.tokenizer) + bpe = task.build_bpe(cfg.bpe) + + def decode_fn(x): + if bpe is not None: + x = bpe.decode(x) + if tokenizer is not None: + x = tokenizer.decode(x) + return x + + scorer = scoring.build_scorer(cfg.scoring, tgt_dict) + + num_sentences = 0 + has_target = True + wps_meter = TimeMeter() + for sample in progress: + sample = utils.move_to_cuda(sample) if use_cuda else sample + if "net_input" not in sample: + continue + + prefix_tokens = None + if cfg.generation.prefix_size > 0: + prefix_tokens = sample["target"][:, : cfg.generation.prefix_size] + + constraints = None + if "constraints" in sample: + constraints = sample["constraints"] + + gen_timer.start() + hypos = task.inference_step( + generator, + models, + sample, + prefix_tokens=prefix_tokens, + constraints=constraints, + ) + num_generated_tokens = sum(len(h[0]["tokens"]) for h in hypos) + gen_timer.stop(num_generated_tokens) + + for i, sample_id in enumerate(sample["id"].tolist()): + has_target = sample["target"] is not None + + # Remove padding + if "src_tokens" in sample["net_input"]: + src_tokens = utils.strip_pad( + sample["net_input"]["src_tokens"][i, :], tgt_dict.pad() + ) + else: + src_tokens = None + + target_tokens = None + if has_target: + target_tokens = ( + utils.strip_pad(sample["target"][i, :], tgt_dict.pad()).int().cpu() + ) + + # Either retrieve the original sentences or regenerate them from tokens. + if align_dict is not None: + src_str = task.dataset(cfg.dataset.gen_subset).src.get_original_text( + sample_id + ) + target_str = task.dataset(cfg.dataset.gen_subset).tgt.get_original_text( + sample_id + ) + else: + if src_dict is not None: + src_str = src_dict.string(src_tokens, cfg.common_eval.post_process) + else: + src_str = "" + if has_target: + target_str = tgt_dict.string( + target_tokens, + cfg.common_eval.post_process, + escape_unk=True, + extra_symbols_to_ignore=get_symbols_to_strip_from_output( + generator + ), + ) + + src_str = decode_fn(src_str) + if has_target: + target_str = decode_fn(target_str) + + if not cfg.common_eval.quiet: + if src_dict is not None: + print("S-{}\t{}".format(sample_id, src_str), file=output_file) + if has_target: + print("T-{}\t{}".format(sample_id, target_str), file=output_file) + + # Process top predictions + for j, hypo in enumerate(hypos[i][: cfg.generation.nbest]): + hypo_tokens, hypo_str, alignment = utils.post_process_prediction( + hypo_tokens=hypo["tokens"].int().cpu(), + src_str=src_str, + alignment=hypo["alignment"], + align_dict=align_dict, + tgt_dict=tgt_dict, + remove_bpe=cfg.common_eval.post_process, + extra_symbols_to_ignore=get_symbols_to_strip_from_output(generator), + ) + detok_hypo_str = decode_fn(hypo_str) + if not cfg.common_eval.quiet: + score = hypo["score"] / math.log(2) # convert to base 2 + # original hypothesis (after tokenization and BPE) + print( + "H-{}\t{}\t{}".format(sample_id, score, hypo_str), + file=output_file, + ) + # detokenized hypothesis + print( + "D-{}\t{}\t{}".format(sample_id, score, detok_hypo_str), + file=output_file, + ) + print( + "P-{}\t{}".format( + sample_id, + " ".join( + map( + lambda x: "{:.4f}".format(x), + # convert from base e to base 2 + hypo["positional_scores"] + .div_(math.log(2)) + .tolist(), + ) + ), + ), + file=output_file, + ) + + if cfg.generation.print_alignment == "hard": + print( + "A-{}\t{}".format( + sample_id, + " ".join( + [ + "{}-{}".format(src_idx, tgt_idx) + for src_idx, tgt_idx in alignment + ] + ), + ), + file=output_file, + ) + if cfg.generation.print_alignment == "soft": + print( + "A-{}\t{}".format( + sample_id, + " ".join( + [",".join(src_probs) for src_probs in alignment] + ), + ), + file=output_file, + ) + + if cfg.generation.print_step: + print( + "I-{}\t{}".format(sample_id, hypo["steps"]), + file=output_file, + ) + + if cfg.generation.retain_iter_history: + for step, h in enumerate(hypo["history"]): + _, h_str, _ = utils.post_process_prediction( + hypo_tokens=h["tokens"].int().cpu(), + src_str=src_str, + alignment=None, + align_dict=None, + tgt_dict=tgt_dict, + remove_bpe=None, + ) + print( + "E-{}_{}\t{}".format(sample_id, step, h_str), + file=output_file, + ) + + # Score only the top hypothesis + if has_target and j == 0: + if ( + align_dict is not None + or cfg.common_eval.post_process is not None + ): + # Convert back to tokens for evaluation with unk replacement and/or without BPE + target_tokens = tgt_dict.encode_line( + target_str, add_if_not_exist=True + ) + hypo_tokens = tgt_dict.encode_line( + detok_hypo_str, add_if_not_exist=True + ) + if hasattr(scorer, "add_string"): + scorer.add_string(target_str, detok_hypo_str) + else: + scorer.add(target_tokens, hypo_tokens) + + wps_meter.update(num_generated_tokens) + progress.log({"wps": round(wps_meter.avg)}) + num_sentences += ( + sample["nsentences"] if "nsentences" in sample else sample["id"].numel() + ) + + logger.info("NOTE: hypothesis and token scores are output in base 2") + logger.info( + "Translated {:,} sentences ({:,} tokens) in {:.1f}s ({:.2f} sentences/s, {:.2f} tokens/s)".format( + num_sentences, + gen_timer.n, + gen_timer.sum, + num_sentences / gen_timer.sum, + 1.0 / gen_timer.avg, + ) + ) + if has_target: + if cfg.bpe and not cfg.generation.sacrebleu: + if cfg.common_eval.post_process: + logger.warning( + "BLEU score is being computed by splitting detokenized string on spaces, this is probably not what you want. Use --sacrebleu for standard 13a BLEU tokenization" + ) + else: + logger.warning( + "If you are using BPE on the target side, the BLEU score is computed on BPE tokens, not on proper words. Use --sacrebleu for standard 13a BLEU tokenization" + ) + # use print to be consistent with other main outputs: S-, H-, T-, D- and so on + print( + "Generate {} with beam={}: {}".format( + cfg.dataset.gen_subset, cfg.generation.beam, scorer.result_string() + ), + file=output_file, + ) + + return scorer + + +def cli_main(): + parser = options.get_generation_parser() + # TODO: replace this workaround with refactoring of `AudioPretraining` + parser.add_argument( + "--arch", + "-a", + metavar="ARCH", + default="wav2vec2", + help="Model architecture. For constructing tasks that rely on " + "model args (e.g. `AudioPretraining`)", + ) + args = options.parse_args_and_arch(parser) + main(args) + + +if __name__ == "__main__": + cli_main() diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/hydra_train.py b/PyTorch/NLP/new-Transformer/fairseq_cli/hydra_train.py new file mode 100644 index 00000000..607340af --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq_cli/hydra_train.py @@ -0,0 +1,91 @@ +#!/usr/bin/env python3 -u +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os + +import hydra +import torch +from hydra.core.hydra_config import HydraConfig +from omegaconf import OmegaConf, open_dict + +from fairseq import distributed_utils, metrics +from fairseq.dataclass.configs import FairseqConfig +from fairseq.dataclass.initialize import add_defaults, hydra_init +from fairseq.dataclass.utils import omegaconf_no_object_check +from fairseq.utils import reset_logging +from fairseq_cli.train import main as pre_main + +logger = logging.getLogger("fairseq_cli.hydra_train") + + +@hydra.main(config_path=os.path.join("..", "fairseq", "config"), config_name="config") +def hydra_main(cfg: FairseqConfig) -> float: + _hydra_main(cfg) + + +def _hydra_main(cfg: FairseqConfig, **kwargs) -> float: + add_defaults(cfg) + + if cfg.common.reset_logging: + reset_logging() # Hydra hijacks logging, fix that + else: + # check if directly called or called through hydra_main + if HydraConfig.initialized(): + with open_dict(cfg): + # make hydra logging work with ddp (see # see https://github.com/facebookresearch/hydra/issues/1126) + cfg.job_logging_cfg = OmegaConf.to_container( + HydraConfig.get().job_logging, resolve=True + ) + + with omegaconf_no_object_check(): + cfg = OmegaConf.create( + OmegaConf.to_container(cfg, resolve=True, enum_to_str=True) + ) + OmegaConf.set_struct(cfg, True) + + try: + if cfg.common.profile: + with torch.cuda.profiler.profile(): + with torch.autograd.profiler.emit_nvtx(): + distributed_utils.call_main(cfg, pre_main, **kwargs) + else: + distributed_utils.call_main(cfg, pre_main, **kwargs) + except BaseException as e: + if not cfg.common.suppress_crashes: + raise + else: + logger.error("Crashed! " + str(e)) + + # get best val and return - useful for sweepers + try: + best_val = metrics.get_smoothed_value( + "valid", cfg.checkpoint.best_checkpoint_metric + ) + except: + best_val = None + + if best_val is None: + best_val = float("inf") + + return best_val + + +def cli_main(): + try: + from hydra._internal.utils import get_args + + cfg_name = get_args().config_name or "config" + except: + logger.warning("Failed to get config name from hydra args") + cfg_name = "config" + + hydra_init(cfg_name) + hydra_main() + + +if __name__ == "__main__": + cli_main() diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/interactive.py b/PyTorch/NLP/new-Transformer/fairseq_cli/interactive.py new file mode 100644 index 00000000..03265d00 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq_cli/interactive.py @@ -0,0 +1,317 @@ +#!/usr/bin/env python3 -u +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Translate raw text with a trained model. Batches data on-the-fly. +""" + +import ast +import fileinput +import logging +import math +import os +import sys +import time +from argparse import Namespace +from collections import namedtuple + +import numpy as np +import torch + +from fairseq import checkpoint_utils, distributed_utils, options, tasks, utils +from fairseq.dataclass.configs import FairseqConfig +from fairseq.dataclass.utils import convert_namespace_to_omegaconf +from fairseq.token_generation_constraints import pack_constraints, unpack_constraints +from fairseq_cli.generate import get_symbols_to_strip_from_output + +logging.basicConfig( + format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + level=os.environ.get("LOGLEVEL", "INFO").upper(), + stream=sys.stdout, +) +logger = logging.getLogger("fairseq_cli.interactive") + + +Batch = namedtuple("Batch", "ids src_tokens src_lengths constraints") +Translation = namedtuple("Translation", "src_str hypos pos_scores alignments") + + +def buffered_read(input, buffer_size): + buffer = [] + with fileinput.input(files=[input], openhook=fileinput.hook_encoded("utf-8")) as h: + for src_str in h: + buffer.append(src_str.strip()) + if len(buffer) >= buffer_size: + yield buffer + buffer = [] + + if len(buffer) > 0: + yield buffer + + +def make_batches(lines, cfg, task, max_positions, encode_fn): + def encode_fn_target(x): + return encode_fn(x) + + if cfg.generation.constraints: + # Strip (tab-delimited) contraints, if present, from input lines, + # store them in batch_constraints + batch_constraints = [list() for _ in lines] + for i, line in enumerate(lines): + if "\t" in line: + lines[i], *batch_constraints[i] = line.split("\t") + + # Convert each List[str] to List[Tensor] + for i, constraint_list in enumerate(batch_constraints): + batch_constraints[i] = [ + task.target_dictionary.encode_line( + encode_fn_target(constraint), + append_eos=False, + add_if_not_exist=False, + ) + for constraint in constraint_list + ] + + if cfg.generation.constraints: + constraints_tensor = pack_constraints(batch_constraints) + else: + constraints_tensor = None + + tokens, lengths = task.get_interactive_tokens_and_lengths(lines, encode_fn) + + itr = task.get_batch_iterator( + dataset=task.build_dataset_for_inference( + tokens, lengths, constraints=constraints_tensor + ), + max_tokens=cfg.dataset.max_tokens, + max_sentences=cfg.dataset.batch_size, + max_positions=max_positions, + ignore_invalid_inputs=cfg.dataset.skip_invalid_size_inputs_valid_test, + ).next_epoch_itr(shuffle=False) + for batch in itr: + ids = batch["id"] + src_tokens = batch["net_input"]["src_tokens"] + src_lengths = batch["net_input"]["src_lengths"] + constraints = batch.get("constraints", None) + + yield Batch( + ids=ids, + src_tokens=src_tokens, + src_lengths=src_lengths, + constraints=constraints, + ) + + +def main(cfg: FairseqConfig): + if isinstance(cfg, Namespace): + cfg = convert_namespace_to_omegaconf(cfg) + + start_time = time.time() + total_translate_time = 0 + + utils.import_user_module(cfg.common) + + if cfg.interactive.buffer_size < 1: + cfg.interactive.buffer_size = 1 + if cfg.dataset.max_tokens is None and cfg.dataset.batch_size is None: + cfg.dataset.batch_size = 1 + + assert ( + not cfg.generation.sampling or cfg.generation.nbest == cfg.generation.beam + ), "--sampling requires --nbest to be equal to --beam" + assert ( + not cfg.dataset.batch_size + or cfg.dataset.batch_size <= cfg.interactive.buffer_size + ), "--batch-size cannot be larger than --buffer-size" + + logger.info(cfg) + + # Fix seed for stochastic decoding + if cfg.common.seed is not None and not cfg.generation.no_seed_provided: + np.random.seed(cfg.common.seed) + utils.set_torch_seed(cfg.common.seed) + + use_cuda = torch.cuda.is_available() and not cfg.common.cpu + + # Setup task, e.g., translation + task = tasks.setup_task(cfg.task) + + # Load ensemble + overrides = ast.literal_eval(cfg.common_eval.model_overrides) + logger.info("loading model(s) from {}".format(cfg.common_eval.path)) + models, _model_args = checkpoint_utils.load_model_ensemble( + utils.split_paths(cfg.common_eval.path), + arg_overrides=overrides, + task=task, + suffix=cfg.checkpoint.checkpoint_suffix, + strict=(cfg.checkpoint.checkpoint_shard_count == 1), + num_shards=cfg.checkpoint.checkpoint_shard_count, + ) + + # Set dictionaries + src_dict = task.source_dictionary + tgt_dict = task.target_dictionary + + # Optimize ensemble for generation + for model in models: + if model is None: + continue + if cfg.common.fp16: + model.half() + if use_cuda and not cfg.distributed_training.pipeline_model_parallel: + model.cuda() + model.prepare_for_inference_(cfg) + + # Initialize generator + generator = task.build_generator(models, cfg.generation) + + # Handle tokenization and BPE + tokenizer = task.build_tokenizer(cfg.tokenizer) + bpe = task.build_bpe(cfg.bpe) + + def encode_fn(x): + if tokenizer is not None: + x = tokenizer.encode(x) + if bpe is not None: + x = bpe.encode(x) + return x + + def decode_fn(x): + if bpe is not None: + x = bpe.decode(x) + if tokenizer is not None: + x = tokenizer.decode(x) + return x + + # Load alignment dictionary for unknown word replacement + # (None if no unknown word replacement, empty if no path to align dictionary) + align_dict = utils.load_align_dict(cfg.generation.replace_unk) + + max_positions = utils.resolve_max_positions( + task.max_positions(), *[model.max_positions() for model in models] + ) + + if cfg.generation.constraints: + logger.warning( + "NOTE: Constrained decoding currently assumes a shared subword vocabulary." + ) + + if cfg.interactive.buffer_size > 1: + logger.info("Sentence buffer size: %s", cfg.interactive.buffer_size) + logger.info("NOTE: hypothesis and token scores are output in base 2") + logger.info("Type the input sentence and press return:") + start_id = 0 + for inputs in buffered_read(cfg.interactive.input, cfg.interactive.buffer_size): + results = [] + for batch in make_batches(inputs, cfg, task, max_positions, encode_fn): + bsz = batch.src_tokens.size(0) + src_tokens = batch.src_tokens + src_lengths = batch.src_lengths + constraints = batch.constraints + if use_cuda: + src_tokens = src_tokens.cuda() + src_lengths = src_lengths.cuda() + if constraints is not None: + constraints = constraints.cuda() + + sample = { + "net_input": { + "src_tokens": src_tokens, + "src_lengths": src_lengths, + }, + } + translate_start_time = time.time() + translations = task.inference_step( + generator, models, sample, constraints=constraints + ) + translate_time = time.time() - translate_start_time + total_translate_time += translate_time + list_constraints = [[] for _ in range(bsz)] + if cfg.generation.constraints: + list_constraints = [unpack_constraints(c) for c in constraints] + for i, (id, hypos) in enumerate(zip(batch.ids.tolist(), translations)): + src_tokens_i = utils.strip_pad(src_tokens[i], tgt_dict.pad()) + constraints = list_constraints[i] + results.append( + ( + start_id + id, + src_tokens_i, + hypos, + { + "constraints": constraints, + "time": translate_time / len(translations), + }, + ) + ) + + # sort output to match input order + for id_, src_tokens, hypos, info in sorted(results, key=lambda x: x[0]): + src_str = "" + if src_dict is not None: + src_str = src_dict.string(src_tokens, cfg.common_eval.post_process) + print("S-{}\t{}".format(id_, src_str)) + print("W-{}\t{:.3f}\tseconds".format(id_, info["time"])) + for constraint in info["constraints"]: + print( + "C-{}\t{}".format( + id_, + tgt_dict.string(constraint, cfg.common_eval.post_process), + ) + ) + + # Process top predictions + for hypo in hypos[: min(len(hypos), cfg.generation.nbest)]: + hypo_tokens, hypo_str, alignment = utils.post_process_prediction( + hypo_tokens=hypo["tokens"].int().cpu(), + src_str=src_str, + alignment=hypo["alignment"], + align_dict=align_dict, + tgt_dict=tgt_dict, + remove_bpe=cfg.common_eval.post_process, + extra_symbols_to_ignore=get_symbols_to_strip_from_output(generator), + ) + detok_hypo_str = decode_fn(hypo_str) + score = hypo["score"] / math.log(2) # convert to base 2 + # original hypothesis (after tokenization and BPE) + print("H-{}\t{}\t{}".format(id_, score, hypo_str)) + # detokenized hypothesis + print("D-{}\t{}\t{}".format(id_, score, detok_hypo_str)) + print( + "P-{}\t{}".format( + id_, + " ".join( + map( + lambda x: "{:.4f}".format(x), + # convert from base e to base 2 + hypo["positional_scores"].div_(math.log(2)).tolist(), + ) + ), + ) + ) + if cfg.generation.print_alignment: + alignment_str = " ".join( + ["{}-{}".format(src, tgt) for src, tgt in alignment] + ) + print("A-{}\t{}".format(id_, alignment_str)) + + # update running id_ counter + start_id += len(inputs) + + logger.info( + "Total time: {:.3f} seconds; translation time: {:.3f}".format( + time.time() - start_time, total_translate_time + ) + ) + + +def cli_main(): + parser = options.get_interactive_generation_parser() + args = options.parse_args_and_arch(parser) + distributed_utils.call_main(convert_namespace_to_omegaconf(args), main) + + +if __name__ == "__main__": + cli_main() diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/preprocess.py b/PyTorch/NLP/new-Transformer/fairseq_cli/preprocess.py new file mode 100644 index 00000000..2ba9e093 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq_cli/preprocess.py @@ -0,0 +1,393 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Data pre-processing: build vocabularies and binarize training data. +""" + +import logging +import os +import shutil +import sys +import typing as tp +from argparse import Namespace +from itertools import zip_longest + +from fairseq import options, tasks, utils +from fairseq.binarizer import ( + AlignmentDatasetBinarizer, + FileBinarizer, + VocabularyDatasetBinarizer, +) +from fairseq.data import Dictionary + +logging.basicConfig( + format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + level=os.environ.get("LOGLEVEL", "INFO").upper(), + stream=sys.stdout, +) +logger = logging.getLogger("fairseq_cli.preprocess") + +##################################################################### +# file name tools +##################################################################### + + +def _train_path(lang, trainpref): + return "{}{}".format(trainpref, ("." + lang) if lang else "") + + +def _file_name(prefix, lang): + fname = prefix + if lang is not None: + fname += ".{lang}".format(lang=lang) + return fname + + +def _dest_path(prefix, lang, destdir): + return os.path.join(destdir, _file_name(prefix, lang)) + + +def _dict_path(lang, destdir): + return _dest_path("dict", lang, destdir) + ".txt" + + +def dataset_dest_prefix(args, output_prefix, lang): + base = os.path.join(args.destdir, output_prefix) + if lang is not None: + lang_part = f".{args.source_lang}-{args.target_lang}.{lang}" + elif args.only_source: + lang_part = "" + else: + lang_part = f".{args.source_lang}-{args.target_lang}" + + return "{}{}".format(base, lang_part) + + +def dataset_dest_file(args, output_prefix, lang, extension): + return "{}.{}".format(dataset_dest_prefix(args, output_prefix, lang), extension) + + +##################################################################### +# dictionary tools +##################################################################### + + +def _build_dictionary( + filenames, + task, + args, + src=False, + tgt=False, +): + assert src ^ tgt + return task.build_dictionary( + filenames, + workers=args.workers, + threshold=args.thresholdsrc if src else args.thresholdtgt, + nwords=args.nwordssrc if src else args.nwordstgt, + padding_factor=args.padding_factor, + ) + + +##################################################################### +# bin file creation logic +##################################################################### + + +def _make_binary_dataset( + vocab: Dictionary, + input_prefix: str, + output_prefix: str, + lang: tp.Optional[str], + num_workers: int, + args: Namespace, +): + logger.info("[{}] Dictionary: {} types".format(lang, len(vocab))) + + binarizer = VocabularyDatasetBinarizer( + vocab, + append_eos=True, + ) + + input_file = "{}{}".format(input_prefix, ("." + lang) if lang is not None else "") + full_output_prefix = dataset_dest_prefix(args, output_prefix, lang) + + final_summary = FileBinarizer.multiprocess_dataset( + input_file, + args.dataset_impl, + binarizer, + full_output_prefix, + vocab_size=len(vocab), + num_workers=num_workers, + ) + + logger.info(f"[{lang}] {input_file}: {final_summary} (by {vocab.unk_word})") + + +def _make_binary_alignment_dataset( + input_prefix: str, output_prefix: str, num_workers: int, args: Namespace +): + + binarizer = AlignmentDatasetBinarizer(utils.parse_alignment) + + input_file = input_prefix + full_output_prefix = dataset_dest_prefix(args, output_prefix, lang=None) + + final_summary = FileBinarizer.multiprocess_dataset( + input_file, + args.dataset_impl, + binarizer, + full_output_prefix, + vocab_size=None, + num_workers=num_workers, + ) + + logger.info( + "[alignments] {}: parsed {} alignments".format( + input_file, final_summary.num_seq + ) + ) + + +##################################################################### +# routing logic +##################################################################### + + +def _make_dataset( + vocab: Dictionary, + input_prefix: str, + output_prefix: str, + lang: tp.Optional[str], + args: Namespace, + num_workers: int, +): + if args.dataset_impl == "raw": + # Copy original text file to destination folder + output_text_file = _dest_path( + output_prefix + ".{}-{}".format(args.source_lang, args.target_lang), + lang, + args.destdir, + ) + shutil.copyfile(_file_name(input_prefix, lang), output_text_file) + else: + _make_binary_dataset( + vocab, input_prefix, output_prefix, lang, num_workers, args + ) + + +def _make_all(lang, vocab, args): + if args.trainpref: + _make_dataset( + vocab, args.trainpref, "train", lang, args=args, num_workers=args.workers + ) + if args.validpref: + for k, validpref in enumerate(args.validpref.split(",")): + outprefix = "valid{}".format(k) if k > 0 else "valid" + _make_dataset( + vocab, validpref, outprefix, lang, args=args, num_workers=args.workers + ) + if args.testpref: + for k, testpref in enumerate(args.testpref.split(",")): + outprefix = "test{}".format(k) if k > 0 else "test" + _make_dataset( + vocab, testpref, outprefix, lang, args=args, num_workers=args.workers + ) + + +def _make_all_alignments(args): + if args.trainpref and os.path.exists(args.trainpref + "." + args.align_suffix): + _make_binary_alignment_dataset( + args.trainpref + "." + args.align_suffix, + "train.align", + num_workers=args.workers, + args=args, + ) + if args.validpref and os.path.exists(args.validpref + "." + args.align_suffix): + _make_binary_alignment_dataset( + args.validpref + "." + args.align_suffix, + "valid.align", + num_workers=args.workers, + args=args, + ) + if args.testpref and os.path.exists(args.testpref + "." + args.align_suffix): + _make_binary_alignment_dataset( + args.testpref + "." + args.align_suffix, + "test.align", + num_workers=args.workers, + args=args, + ) + + +##################################################################### +# align +##################################################################### + + +def _align_files(args, src_dict, tgt_dict): + assert args.trainpref, "--trainpref must be set if --alignfile is specified" + src_file_name = _train_path(args.source_lang, args.trainpref) + tgt_file_name = _train_path(args.target_lang, args.trainpref) + freq_map = {} + with open(args.alignfile, "r", encoding="utf-8") as align_file: + with open(src_file_name, "r", encoding="utf-8") as src_file: + with open(tgt_file_name, "r", encoding="utf-8") as tgt_file: + for a, s, t in zip_longest(align_file, src_file, tgt_file): + si = src_dict.encode_line(s, add_if_not_exist=False) + ti = tgt_dict.encode_line(t, add_if_not_exist=False) + ai = list(map(lambda x: tuple(x.split("-")), a.split())) + for sai, tai in ai: + srcidx = si[int(sai)] + tgtidx = ti[int(tai)] + if srcidx != src_dict.unk() and tgtidx != tgt_dict.unk(): + assert srcidx != src_dict.pad() + assert srcidx != src_dict.eos() + assert tgtidx != tgt_dict.pad() + assert tgtidx != tgt_dict.eos() + if srcidx not in freq_map: + freq_map[srcidx] = {} + if tgtidx not in freq_map[srcidx]: + freq_map[srcidx][tgtidx] = 1 + else: + freq_map[srcidx][tgtidx] += 1 + align_dict = {} + for srcidx in freq_map.keys(): + align_dict[srcidx] = max(freq_map[srcidx], key=freq_map[srcidx].get) + with open( + os.path.join( + args.destdir, + "alignment.{}-{}.txt".format(args.source_lang, args.target_lang), + ), + "w", + encoding="utf-8", + ) as f: + for k, v in align_dict.items(): + print("{} {}".format(src_dict[k], tgt_dict[v]), file=f) + + +##################################################################### +# MAIN +##################################################################### + + +def main(args): + # setup some basic things + utils.import_user_module(args) + + os.makedirs(args.destdir, exist_ok=True) + + logger.addHandler( + logging.FileHandler( + filename=os.path.join(args.destdir, "preprocess.log"), + ) + ) + logger.info(args) + + assert ( + args.dataset_impl != "huffman" + ), "preprocessing.py doesn't support Huffman yet, use HuffmanCodeBuilder directly." + + # build dictionaries + + target = not args.only_source + + if not args.srcdict and os.path.exists(_dict_path(args.source_lang, args.destdir)): + raise FileExistsError(_dict_path(args.source_lang, args.destdir)) + + if ( + target + and not args.tgtdict + and os.path.exists(_dict_path(args.target_lang, args.destdir)) + ): + raise FileExistsError(_dict_path(args.target_lang, args.destdir)) + + task = tasks.get_task(args.task) + + if args.joined_dictionary: + assert ( + not args.srcdict or not args.tgtdict + ), "cannot use both --srcdict and --tgtdict with --joined-dictionary" + + if args.srcdict: + src_dict = task.load_dictionary(args.srcdict) + elif args.tgtdict: + src_dict = task.load_dictionary(args.tgtdict) + else: + assert ( + args.trainpref + ), "--trainpref must be set if --srcdict is not specified" + src_dict = _build_dictionary( + { + _train_path(lang, args.trainpref) + for lang in [args.source_lang, args.target_lang] + }, + task=task, + args=args, + src=True, + ) + tgt_dict = src_dict + else: + if args.srcdict: + src_dict = task.load_dictionary(args.srcdict) + else: + assert ( + args.trainpref + ), "--trainpref must be set if --srcdict is not specified" + src_dict = _build_dictionary( + [_train_path(args.source_lang, args.trainpref)], + task=task, + args=args, + src=True, + ) + + if target: + if args.tgtdict: + tgt_dict = task.load_dictionary(args.tgtdict) + else: + assert ( + args.trainpref + ), "--trainpref must be set if --tgtdict is not specified" + tgt_dict = _build_dictionary( + [_train_path(args.target_lang, args.trainpref)], + task=task, + args=args, + tgt=True, + ) + else: + tgt_dict = None + + # save dictionaries + + src_dict.save(_dict_path(args.source_lang, args.destdir)) + if target and tgt_dict is not None: + tgt_dict.save(_dict_path(args.target_lang, args.destdir)) + + if args.dict_only: + return + + _make_all(args.source_lang, src_dict, args) + if target: + _make_all(args.target_lang, tgt_dict, args) + + # align the datasets if needed + if args.align_suffix: + _make_all_alignments(args) + + logger.info("Wrote preprocessed data to {}".format(args.destdir)) + + if args.alignfile: + _align_files(args, src_dict=src_dict, tgt_dict=tgt_dict) + + +def cli_main(): + parser = options.get_preprocessing_parser() + args = parser.parse_args() + main(args) + + +if __name__ == "__main__": + cli_main() diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/score.py b/PyTorch/NLP/new-Transformer/fairseq_cli/score.py new file mode 100644 index 00000000..0b207be9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq_cli/score.py @@ -0,0 +1,102 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +BLEU scoring of generated translations against reference translations. +""" + +import argparse +import os +import sys + +from fairseq.data import dictionary +from fairseq.scoring import bleu + + +def get_parser(): + parser = argparse.ArgumentParser( + description="Command-line script for BLEU scoring." + ) + # fmt: off + parser.add_argument('-s', '--sys', default='-', help='system output') + parser.add_argument('-r', '--ref', required=True, help='references') + parser.add_argument('-o', '--order', default=4, metavar='N', + type=int, help='consider ngrams up to this order') + parser.add_argument('--ignore-case', action='store_true', + help='case-insensitive scoring') + parser.add_argument('--sacrebleu', action='store_true', + help='score with sacrebleu') + parser.add_argument('--sentence-bleu', action='store_true', + help='report sentence-level BLEUs (i.e., with +1 smoothing)') + # fmt: on + return parser + + +def cli_main(): + parser = get_parser() + args = parser.parse_args() + print(args) + + assert args.sys == "-" or os.path.exists( + args.sys + ), "System output file {} does not exist".format(args.sys) + assert os.path.exists(args.ref), "Reference file {} does not exist".format(args.ref) + + dict = dictionary.Dictionary() + + def readlines(fd): + for line in fd.readlines(): + if args.ignore_case: + yield line.lower() + else: + yield line + + if args.sacrebleu: + import sacrebleu + + def score(fdsys): + with open(args.ref) as fdref: + print(sacrebleu.corpus_bleu(fdsys, [fdref]).format()) + + elif args.sentence_bleu: + + def score(fdsys): + with open(args.ref) as fdref: + scorer = bleu.Scorer(dict.pad(), dict.eos(), dict.unk()) + for i, (sys_tok, ref_tok) in enumerate( + zip(readlines(fdsys), readlines(fdref)) + ): + scorer.reset(one_init=True) + sys_tok = dict.encode_line(sys_tok) + ref_tok = dict.encode_line(ref_tok) + scorer.add(ref_tok, sys_tok) + print(i, scorer.result_string(args.order)) + + else: + + def score(fdsys): + with open(args.ref) as fdref: + scorer = bleu.Scorer( + bleu.BleuConfig( + pad=dict.pad(), + eos=dict.eos(), + unk=dict.unk(), + ) + ) + for sys_tok, ref_tok in zip(readlines(fdsys), readlines(fdref)): + sys_tok = dict.encode_line(sys_tok) + ref_tok = dict.encode_line(ref_tok) + scorer.add(ref_tok, sys_tok) + print(scorer.result_string(args.order)) + + if args.sys == "-": + score(sys.stdin) + else: + with open(args.sys, "r") as f: + score(f) + + +if __name__ == "__main__": + cli_main() diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/train.py b/PyTorch/NLP/new-Transformer/fairseq_cli/train.py new file mode 100644 index 00000000..376bd1d0 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq_cli/train.py @@ -0,0 +1,564 @@ +#!/usr/bin/env python3 -u +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Train a new model on one or across multiple GPUs. +""" + +import argparse +import logging +import math +import os +import sys +from typing import Any, Callable, Dict, List, Optional, Tuple + +# We need to setup root logger before importing any fairseq libraries. +logging.basicConfig( + format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + level=os.environ.get("LOGLEVEL", "INFO").upper(), + stream=sys.stdout, +) +logger = logging.getLogger("fairseq_cli.train") + +import numpy as np +import torch +from omegaconf import DictConfig, OmegaConf + +from fairseq import checkpoint_utils, options, quantization_utils, tasks, utils +from fairseq.data import data_utils, iterators +from fairseq.data.plasma_utils import PlasmaStore +from fairseq.dataclass.configs import FairseqConfig +from fairseq.dataclass.initialize import add_defaults +from fairseq.dataclass.utils import convert_namespace_to_omegaconf +from fairseq.distributed import fsdp_enable_wrap, fsdp_wrap +from fairseq.distributed import utils as distributed_utils +from fairseq.file_io import PathManager +from fairseq.logging import meters, metrics, progress_bar +from fairseq.model_parallel.megatron_trainer import MegatronTrainer +from fairseq.trainer import Trainer + + +def main(cfg: FairseqConfig) -> None: + if isinstance(cfg, argparse.Namespace): + cfg = convert_namespace_to_omegaconf(cfg) + + utils.import_user_module(cfg.common) + add_defaults(cfg) + + if ( + distributed_utils.is_master(cfg.distributed_training) + and "job_logging_cfg" in cfg + ): + # make hydra logging work with ddp (see # see https://github.com/facebookresearch/hydra/issues/1126) + logging.config.dictConfig(OmegaConf.to_container(cfg.job_logging_cfg)) + + assert ( + cfg.dataset.max_tokens is not None or cfg.dataset.batch_size is not None + ), "Must specify batch size either with --max-tokens or --batch-size" + metrics.reset() + + if cfg.common.log_file is not None: + handler = logging.FileHandler(filename=cfg.common.log_file) + logger.addHandler(handler) + + np.random.seed(cfg.common.seed) + utils.set_torch_seed(cfg.common.seed) + + if distributed_utils.is_master(cfg.distributed_training): + checkpoint_utils.verify_checkpoint_directory(cfg.checkpoint.save_dir) + + # Print args + logger.info(cfg) + + if cfg.checkpoint.write_checkpoints_asynchronously: + try: + import iopath # noqa: F401 + except ImportError: + logging.exception( + "Asynchronous checkpoint writing is specified but iopath is " + "not installed: `pip install iopath`" + ) + return + + # Setup task, e.g., translation, language modeling, etc. + task = tasks.setup_task(cfg.task) + + assert cfg.criterion, "Please specify criterion to train a model" + + # Build model and criterion + if cfg.distributed_training.ddp_backend == "fully_sharded": + with fsdp_enable_wrap(cfg.distributed_training): + model = fsdp_wrap(task.build_model(cfg.model)) + else: + model = task.build_model(cfg.model) + criterion = task.build_criterion(cfg.criterion) + logger.info(model) + logger.info("task: {}".format(task.__class__.__name__)) + logger.info("model: {}".format(model.__class__.__name__)) + logger.info("criterion: {}".format(criterion.__class__.__name__)) + logger.info( + "num. shared model params: {:,} (num. trained: {:,})".format( + sum( + p.numel() for p in model.parameters() if not getattr(p, "expert", False) + ), + sum( + p.numel() + for p in model.parameters() + if not getattr(p, "expert", False) and p.requires_grad + ), + ) + ) + + logger.info( + "num. expert model params: {} (num. trained: {})".format( + sum(p.numel() for p in model.parameters() if getattr(p, "expert", False)), + sum( + p.numel() + for p in model.parameters() + if getattr(p, "expert", False) and p.requires_grad + ), + ) + ) + + # Load valid dataset (we load training data below, based on the latest checkpoint) + # We load the valid dataset AFTER building the model + data_utils.raise_if_valid_subsets_unintentionally_ignored(cfg) + if cfg.dataset.combine_valid_subsets: + task.load_dataset("valid", combine=True, epoch=1) + else: + for valid_sub_split in cfg.dataset.valid_subset.split(","): + task.load_dataset(valid_sub_split, combine=False, epoch=1) + + # (optionally) Configure quantization + if cfg.common.quantization_config_path is not None: + quantizer = quantization_utils.Quantizer( + config_path=cfg.common.quantization_config_path, + max_epoch=cfg.optimization.max_epoch, + max_update=cfg.optimization.max_update, + ) + else: + quantizer = None + + # Build trainer + if cfg.common.model_parallel_size == 1: + trainer = Trainer(cfg, task, model, criterion, quantizer) + else: + trainer = MegatronTrainer(cfg, task, model, criterion) + logger.info( + "training on {} devices (GPUs/TPUs)".format( + cfg.distributed_training.distributed_world_size + ) + ) + logger.info( + "max tokens per device = {} and max sentences per device = {}".format( + cfg.dataset.max_tokens, + cfg.dataset.batch_size, + ) + ) + + # Load the latest checkpoint if one is available and restore the + # corresponding train iterator + extra_state, epoch_itr = checkpoint_utils.load_checkpoint( + cfg.checkpoint, + trainer, + # don't cache epoch iterators for sharded datasets + disable_iterator_cache=task.has_sharded_data("train"), + ) + if cfg.common.tpu: + import torch_xla.core.xla_model as xm + + xm.rendezvous("load_checkpoint") # wait for all workers + + max_epoch = cfg.optimization.max_epoch or math.inf + lr = trainer.get_lr() + + train_meter = meters.StopwatchMeter() + train_meter.start() + while epoch_itr.next_epoch_idx <= max_epoch: + if lr <= cfg.optimization.stop_min_lr: + logger.info( + f"stopping training because current learning rate ({lr}) is smaller " + "than or equal to minimum learning rate " + f"(--stop-min-lr={cfg.optimization.stop_min_lr})" + ) + break + + # train for one epoch + valid_losses, should_stop = train(cfg, trainer, task, epoch_itr) + if should_stop: + break + + # only use first validation loss to update the learning rate + lr = trainer.lr_step(epoch_itr.epoch, valid_losses[0]) + + epoch_itr = trainer.get_train_iterator( + epoch_itr.next_epoch_idx, + # sharded data: get train iterator for next epoch + load_dataset=task.has_sharded_data("train"), + # don't cache epoch iterators for sharded datasets + disable_iterator_cache=task.has_sharded_data("train"), + ) + train_meter.stop() + logger.info("done training in {:.1f} seconds".format(train_meter.sum)) + + # ioPath implementation to wait for all asynchronous file writes to complete. + if cfg.checkpoint.write_checkpoints_asynchronously: + logger.info( + "ioPath PathManager waiting for all asynchronous checkpoint " + "writes to finish." + ) + PathManager.async_close() + logger.info("ioPath PathManager finished waiting.") + + +def should_stop_early(cfg: DictConfig, valid_loss: float) -> bool: + # skip check if no validation was done in the current epoch + if valid_loss is None: + return False + if cfg.checkpoint.patience <= 0: + return False + + def is_better(a, b): + return a > b if cfg.checkpoint.maximize_best_checkpoint_metric else a < b + + prev_best = getattr(should_stop_early, "best", None) + if prev_best is None or is_better(valid_loss, prev_best): + should_stop_early.best = valid_loss + should_stop_early.num_runs = 0 + return False + else: + should_stop_early.num_runs += 1 + if should_stop_early.num_runs >= cfg.checkpoint.patience: + logger.info( + "early stop since valid performance hasn't improved for last {} runs".format( + cfg.checkpoint.patience + ) + ) + return True + else: + return False + + +@metrics.aggregate("train") +def train( + cfg: DictConfig, trainer: Trainer, task: tasks.FairseqTask, epoch_itr +) -> Tuple[List[Optional[float]], bool]: + """Train the model for one epoch and return validation losses.""" + # Initialize data iterator + itr = epoch_itr.next_epoch_itr( + fix_batches_to_gpus=cfg.distributed_training.fix_batches_to_gpus, + shuffle=(epoch_itr.next_epoch_idx > cfg.dataset.curriculum), + ) + update_freq = ( + cfg.optimization.update_freq[epoch_itr.epoch - 1] + if epoch_itr.epoch <= len(cfg.optimization.update_freq) + else cfg.optimization.update_freq[-1] + ) + itr = iterators.GroupedIterator( + itr, + update_freq, + skip_remainder_batch=cfg.optimization.skip_remainder_batch, + ) + if cfg.common.tpu: + itr = utils.tpu_data_loader(itr) + progress = progress_bar.progress_bar( + itr, + log_format=cfg.common.log_format, + log_file=cfg.common.log_file, + log_interval=cfg.common.log_interval, + epoch=epoch_itr.epoch, + aim_repo=( + cfg.common.aim_repo + if distributed_utils.is_master(cfg.distributed_training) + else None + ), + aim_run_hash=( + cfg.common.aim_run_hash + if distributed_utils.is_master(cfg.distributed_training) + else None + ), + aim_param_checkpoint_dir=cfg.checkpoint.save_dir, + tensorboard_logdir=( + cfg.common.tensorboard_logdir + if distributed_utils.is_master(cfg.distributed_training) + else None + ), + default_log_format=("tqdm" if not cfg.common.no_progress_bar else "simple"), + wandb_project=( + cfg.common.wandb_project + if distributed_utils.is_master(cfg.distributed_training) + else None + ), + wandb_run_name=os.environ.get( + "WANDB_NAME", os.path.basename(cfg.checkpoint.save_dir) + ), + azureml_logging=( + cfg.common.azureml_logging + if distributed_utils.is_master(cfg.distributed_training) + else False + ), + ) + progress.update_config(_flatten_config(cfg)) + + trainer.begin_epoch(epoch_itr.epoch) + + valid_subsets = cfg.dataset.valid_subset.split(",") + should_stop = False + num_updates = trainer.get_num_updates() + logger.info("Start iterating over samples") + for i, samples in enumerate(progress): + with metrics.aggregate("train_inner"), torch.autograd.profiler.record_function( + "train_step-%d" % i + ): + log_output = trainer.train_step(samples) + + if log_output is not None: # not OOM, overflow, ... + # log mid-epoch stats + num_updates = trainer.get_num_updates() + if num_updates % cfg.common.log_interval == 0: + stats = get_training_stats(metrics.get_smoothed_values("train_inner")) + progress.log(stats, tag="train_inner", step=num_updates) + + # reset mid-epoch stats after each log interval + # the end-of-epoch stats will still be preserved + metrics.reset_meters("train_inner") + + end_of_epoch = not itr.has_next() + valid_losses, should_stop = validate_and_save( + cfg, trainer, task, epoch_itr, valid_subsets, end_of_epoch + ) + + if should_stop: + break + + # log end-of-epoch stats + logger.info("end of epoch {} (average epoch stats below)".format(epoch_itr.epoch)) + stats = get_training_stats(metrics.get_smoothed_values("train")) + progress.print(stats, tag="train", step=num_updates) + + # reset epoch-level meters + metrics.reset_meters("train") + return valid_losses, should_stop + + +def _flatten_config(cfg: DictConfig): + config = OmegaConf.to_container(cfg) + # remove any legacy Namespaces and replace with a single "args" + namespace = None + for k, v in list(config.items()): + if isinstance(v, argparse.Namespace): + namespace = v + del config[k] + if namespace is not None: + config["args"] = vars(namespace) + return config + + +def validate_and_save( + cfg: DictConfig, + trainer: Trainer, + task: tasks.FairseqTask, + epoch_itr, + valid_subsets: List[str], + end_of_epoch: bool, +) -> Tuple[List[Optional[float]], bool]: + num_updates = trainer.get_num_updates() + max_update = cfg.optimization.max_update or math.inf + + # Stopping conditions (and an additional one based on validation loss later + # on) + should_stop = False + if num_updates >= max_update: + should_stop = True + logger.info( + f"Stopping training due to " + f"num_updates: {num_updates} >= max_update: {max_update}" + ) + + training_time_hours = trainer.cumulative_training_time() / (60 * 60) + if ( + cfg.optimization.stop_time_hours > 0 + and training_time_hours > cfg.optimization.stop_time_hours + ): + should_stop = True + logger.info( + f"Stopping training due to " + f"cumulative_training_time: {training_time_hours} > " + f"stop_time_hours: {cfg.optimization.stop_time_hours} hour(s)" + ) + + do_save = ( + (end_of_epoch and epoch_itr.epoch % cfg.checkpoint.save_interval == 0) + or should_stop + or ( + cfg.checkpoint.save_interval_updates > 0 + and num_updates > 0 + and num_updates % cfg.checkpoint.save_interval_updates == 0 + and num_updates >= cfg.dataset.validate_after_updates + ) + ) + do_validate = ( + ( + (not end_of_epoch and do_save) # validate during mid-epoch saves + or (end_of_epoch and epoch_itr.epoch % cfg.dataset.validate_interval == 0) + or should_stop + or ( + cfg.dataset.validate_interval_updates > 0 + and num_updates > 0 + and num_updates % cfg.dataset.validate_interval_updates == 0 + ) + ) + and not cfg.dataset.disable_validation + and num_updates >= cfg.dataset.validate_after_updates + ) + + # Validate + valid_losses = [None] + if do_validate: + valid_losses = validate(cfg, trainer, task, epoch_itr, valid_subsets) + + should_stop |= should_stop_early(cfg, valid_losses[0]) + + # Save checkpoint + if do_save or should_stop: + checkpoint_utils.save_checkpoint( + cfg.checkpoint, trainer, epoch_itr, valid_losses[0] + ) + + return valid_losses, should_stop + + +def get_training_stats(stats: Dict[str, Any]) -> Dict[str, Any]: + stats["wall"] = round(metrics.get_meter("default", "wall").elapsed_time, 0) + return stats + + +def validate( + cfg: DictConfig, + trainer: Trainer, + task: tasks.FairseqTask, + epoch_itr, + subsets: List[str], +) -> List[Optional[float]]: + """Evaluate the model on the validation set(s) and return the losses.""" + + if cfg.dataset.fixed_validation_seed is not None: + # set fixed seed for every validation + utils.set_torch_seed(cfg.dataset.fixed_validation_seed) + + trainer.begin_valid_epoch(epoch_itr.epoch) + valid_losses = [] + for subset_idx, subset in enumerate(subsets): + logger.info('begin validation on "{}" subset'.format(subset)) + + # Initialize data iterator + itr = trainer.get_valid_iterator(subset).next_epoch_itr( + shuffle=False, set_dataset_epoch=False # use a fixed valid set + ) + if cfg.common.tpu: + itr = utils.tpu_data_loader(itr) + progress = progress_bar.progress_bar( + itr, + log_format=cfg.common.log_format, + log_interval=cfg.common.log_interval, + epoch=epoch_itr.epoch, + prefix=f"valid on '{subset}' subset", + aim_repo=( + cfg.common.aim_repo + if distributed_utils.is_master(cfg.distributed_training) + else None + ), + aim_run_hash=( + cfg.common.aim_run_hash + if distributed_utils.is_master(cfg.distributed_training) + else None + ), + aim_param_checkpoint_dir=cfg.checkpoint.save_dir, + tensorboard_logdir=( + cfg.common.tensorboard_logdir + if distributed_utils.is_master(cfg.distributed_training) + else None + ), + default_log_format=("tqdm" if not cfg.common.no_progress_bar else "simple"), + wandb_project=( + cfg.common.wandb_project + if distributed_utils.is_master(cfg.distributed_training) + else None + ), + wandb_run_name=os.environ.get( + "WANDB_NAME", os.path.basename(cfg.checkpoint.save_dir) + ), + ) + + # create a new root metrics aggregator so validation metrics + # don't pollute other aggregators (e.g., train meters) + with metrics.aggregate(new_root=True) as agg: + for i, sample in enumerate(progress): + if ( + cfg.dataset.max_valid_steps is not None + and i > cfg.dataset.max_valid_steps + ): + break + trainer.valid_step(sample) + + # log validation stats + # only tracking the best metric on the 1st validation subset + tracking_best = subset_idx == 0 + stats = get_valid_stats(cfg, trainer, agg.get_smoothed_values(), tracking_best) + + if hasattr(task, "post_validate"): + task.post_validate(trainer.get_model(), stats, agg) + + progress.print(stats, tag=subset, step=trainer.get_num_updates()) + + valid_losses.append(stats[cfg.checkpoint.best_checkpoint_metric]) + return valid_losses + + +def get_valid_stats( + cfg: DictConfig, + trainer: Trainer, + stats: Dict[str, Any], + tracking_best: bool, +) -> Dict[str, Any]: + stats["num_updates"] = trainer.get_num_updates() + if tracking_best and hasattr(checkpoint_utils.save_checkpoint, "best"): + key = "best_{0}".format(cfg.checkpoint.best_checkpoint_metric) + best_function = max if cfg.checkpoint.maximize_best_checkpoint_metric else min + stats[key] = best_function( + checkpoint_utils.save_checkpoint.best, + stats[cfg.checkpoint.best_checkpoint_metric], + ) + return stats + + +def cli_main( + modify_parser: Optional[Callable[[argparse.ArgumentParser], None]] = None +) -> None: + parser = options.get_training_parser() + args = options.parse_args_and_arch(parser, modify_parser=modify_parser) + + cfg = convert_namespace_to_omegaconf(args) + + if cfg.common.use_plasma_view: + server = PlasmaStore(path=cfg.common.plasma_path) + logger.info( + f"Started plasma server pid {server.server.pid} {cfg.common.plasma_path}" + ) + + if args.profile: + with torch.cuda.profiler.profile(): + with torch.autograd.profiler.emit_nvtx(): + distributed_utils.call_main(cfg, main) + else: + distributed_utils.call_main(cfg, main) + + # if cfg.common.use_plasma_view: + # server.server.kill() + + +if __name__ == "__main__": + cli_main() diff --git a/PyTorch/NLP/new-Transformer/fairseq_cli/validate.py b/PyTorch/NLP/new-Transformer/fairseq_cli/validate.py new file mode 100644 index 00000000..4617b6d5 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fairseq_cli/validate.py @@ -0,0 +1,153 @@ +#!/usr/bin/env python3 -u +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import logging +import os +import sys +from argparse import Namespace +from itertools import chain + +import torch +from omegaconf import DictConfig + +from fairseq import checkpoint_utils, distributed_utils, options, utils +from fairseq.dataclass.utils import convert_namespace_to_omegaconf +from fairseq.logging import metrics, progress_bar +from fairseq.utils import reset_logging + +logging.basicConfig( + format="%(asctime)s | %(levelname)s | %(name)s | %(message)s", + datefmt="%Y-%m-%d %H:%M:%S", + level=os.environ.get("LOGLEVEL", "INFO").upper(), + stream=sys.stdout, +) +logger = logging.getLogger("fairseq_cli.validate") + + +def main(cfg: DictConfig, override_args=None): + if isinstance(cfg, Namespace): + cfg = convert_namespace_to_omegaconf(cfg) + + utils.import_user_module(cfg.common) + + reset_logging() + + assert ( + cfg.dataset.max_tokens is not None or cfg.dataset.batch_size is not None + ), "Must specify batch size either with --max-tokens or --batch-size" + + use_fp16 = cfg.common.fp16 + use_cuda = torch.cuda.is_available() and not cfg.common.cpu + + if use_cuda: + torch.cuda.set_device(cfg.distributed_training.device_id) + + if cfg.distributed_training.distributed_world_size > 1: + data_parallel_world_size = distributed_utils.get_data_parallel_world_size() + data_parallel_rank = distributed_utils.get_data_parallel_rank() + else: + data_parallel_world_size = 1 + data_parallel_rank = 0 + + if override_args is not None: + overrides = vars(override_args) + overrides.update(eval(getattr(override_args, "model_overrides", "{}"))) + else: + overrides = None + + # Load ensemble + logger.info("loading model(s) from {}".format(cfg.common_eval.path)) + models, saved_cfg, task = checkpoint_utils.load_model_ensemble_and_task( + [cfg.common_eval.path], + arg_overrides=overrides, + suffix=cfg.checkpoint.checkpoint_suffix, + ) + model = models[0] + + # Move models to GPU + for model in models: + model.eval() + if use_fp16: + model.half() + if use_cuda: + model.cuda() + + # Print args + logger.info(saved_cfg) + + # Build criterion + criterion = task.build_criterion(saved_cfg.criterion) + criterion.eval() + + for subset in cfg.dataset.valid_subset.split(","): + try: + task.load_dataset(subset, combine=False, epoch=1, task_cfg=saved_cfg.task) + dataset = task.dataset(subset) + except KeyError: + raise Exception("Cannot find dataset: " + subset) + + # Initialize data iterator + itr = task.get_batch_iterator( + dataset=dataset, + max_tokens=cfg.dataset.max_tokens, + max_sentences=cfg.dataset.batch_size, + max_positions=utils.resolve_max_positions( + task.max_positions(), + *[m.max_positions() for m in models], + ), + ignore_invalid_inputs=cfg.dataset.skip_invalid_size_inputs_valid_test, + required_batch_size_multiple=cfg.dataset.required_batch_size_multiple, + seed=cfg.common.seed, + num_shards=data_parallel_world_size, + shard_id=data_parallel_rank, + num_workers=cfg.dataset.num_workers, + data_buffer_size=cfg.dataset.data_buffer_size, + ).next_epoch_itr(shuffle=False) + progress = progress_bar.progress_bar( + itr, + log_format=cfg.common.log_format, + log_interval=cfg.common.log_interval, + prefix=f"valid on '{subset}' subset", + default_log_format=("tqdm" if not cfg.common.no_progress_bar else "simple"), + ) + + log_outputs = [] + for i, sample in enumerate(progress): + sample = utils.move_to_cuda(sample) if use_cuda else sample + _loss, _sample_size, log_output = task.valid_step(sample, model, criterion) + progress.log(log_output, step=i) + log_outputs.append(log_output) + + if data_parallel_world_size > 1: + log_outputs = distributed_utils.all_gather_list( + log_outputs, + max_size=cfg.common.all_gather_list_size, + group=distributed_utils.get_data_parallel_group(), + ) + log_outputs = list(chain.from_iterable(log_outputs)) + + with metrics.aggregate() as agg: + task.reduce_metrics(log_outputs, criterion) + log_output = agg.get_smoothed_values() + + progress.print(log_output, tag=subset, step=i) + + +def cli_main(): + parser = options.get_validation_parser() + args = options.parse_args_and_arch(parser) + + # only override args that are explicitly given on the command line + override_parser = options.get_validation_parser() + override_args = options.parse_args_and_arch(override_parser, suppress_defaults=True) + + distributed_utils.call_main( + convert_namespace_to_omegaconf(args), main, override_args=override_args + ) + + +if __name__ == "__main__": + cli_main() diff --git a/PyTorch/NLP/new-Transformer/fp16_run_transformer.sh b/PyTorch/NLP/new-Transformer/fp16_run_transformer.sh new file mode 100644 index 00000000..80570b66 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fp16_run_transformer.sh @@ -0,0 +1,20 @@ +export HSA_FORCE_FINE_GRAIN_PCIE=1 +export MIOPEN_FIND_MODE=1 +export HIP_VISIBLE_DEVICES=0 +export DATA_PATH=~/data/wmt14_en_de_joined_dict +export TOKEN=2560 +python3 train.py \ + $DATA_PATH \ + --save-dir module-fp16_2560 \ + --arch transformer_wmt_en_de --share-decoder-input-output-embed \ + --optimizer adam --adam-betas '(0.9, 0.98)' --clip-norm 0.0 \ + --lr 5e-4 --lr-scheduler inverse_sqrt --warmup-updates 4000 \ + --dropout 0.3 --weight-decay 0.0001 \ + --criterion label_smoothed_cross_entropy --label-smoothing 0.1 \ + --max-tokens ${TOKEN} \ + --eval-bleu \ + --eval-bleu-args '{"beam": 5, "max_len_a": 1.2, "max_len_b": 10}' \ + --eval-bleu-detok moses \ + --eval-bleu-remove-bpe \ + --eval-bleu-print-samples \ + --best-checkpoint-metric bleu --maximize-best-checkpoint-metric --max-epoch 1 --fp16 diff --git a/PyTorch/NLP/new-Transformer/fp16_run_transformer_4dcus.sh b/PyTorch/NLP/new-Transformer/fp16_run_transformer_4dcus.sh new file mode 100644 index 00000000..215962b8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fp16_run_transformer_4dcus.sh @@ -0,0 +1,23 @@ +#!/usr/bin/env bash +#SBATCH -J transformer +#SBATCH -p wzhdtest +#SBATCH -N 1 +#SBARCH -n 32 +#SBATCH --ntasks-per-node=4 +#SBATCH --cpus-per-task=8 +#SBATCH --gres=dcu:4 +set -x +hostfile=./$SLURM_JOB_ID +scontrol show hostnames $SLURM_JOB_NODELIST > ${hostfile} +for i in `cat $hostfile` +do + echo ${i} slots=4 >> `pwd`/hostfile-$SLURM_JOB_ID + ((num_node=${num_node}+1)) +done +num_dcu=$((${num_node}*4)) +echo $num_dcu +nodename=$(cat $hostfile |sed -n "1p") +echo $nodename +dist_url=`echo $nodename | awk '{print $1}'` +export HSA_USERPTR_FOR_PAGED_MEM=0 +mpirun -np ${num_dcu} --hostfile hostfile-$SLURM_JOB_ID single_fp16.sh $dist_ur diff --git a/PyTorch/NLP/new-Transformer/fp16_single_process.sh b/PyTorch/NLP/new-Transformer/fp16_single_process.sh new file mode 100644 index 00000000..57cab698 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/fp16_single_process.sh @@ -0,0 +1,42 @@ + +export HIP_VISIBLE_DEVICES=0 +export MIOPEN_DEBUG_DISABLE_FIND_DB=1 +export NCCL_SOCKET_IFNAME=eno1 +export HSA_USERPTR_FOR_PAGED_MEM=0 +lrank=$OMPI_COMM_WORLD_LOCAL_RANK +comm_rank=$OMPI_COMM_WORLD_RANK +comm_size=$OMPI_COMM_WORLD_SIZE +TOKENS=2560 +DATA_PATH=~/data/wmt14_en_de_joined_dict +APP="python3 ~/fairseq/train.py $DATA_PATH --arch transformer_wmt_en_de --share-decoder-input-output-embed --optimizer adam --adam-betas '(0.9,0.98)' --clip-norm 0.0 --lr 5e-4 --lr-scheduler inverse_sqrt --warmup-updates 4000 --dropout 0.3 --weight-decay 0.0001 --criterion label_smoothed_cross_entropy --label-smoothing 0.1 --max-tokens $TOKENS --eval-bleu --eval-bleu-args {\"beam\":5,\"max_len_a\":1.2,\"max_len_b\":10} --eval-bleu-detok moses --eval-bleu-remove-bpe --eval-bleu-print-samples --best-checkpoint-metric bleu --maximize-best-checkpoint-metric --distributed-rank ${comm_rank} --distributed-world-size ${comm_size} --device-id ${lrank} --local_rank ${lrank} --distributed-init-method tcp://${1}:34567 --distributed-no-spawn --max-epoch 1 --fp16" +case ${lrank} in +[0]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_0:1 + export UCX_IB_PCI_BW=mlx5_0:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + ;; +[1]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_1:1 + export UCX_IB_PCI_BW=mlx5_1:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + ;; +[2]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_2:1 + export UCX_IB_PCI_BW=mlx5_2:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + ;; +[3]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_3:1 + export UCX_IB_PCI_BW=mlx5_3:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + ;; +esac + diff --git a/PyTorch/NLP/new-Transformer/hubconf.py b/PyTorch/NLP/new-Transformer/hubconf.py new file mode 100644 index 00000000..5949e274 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/hubconf.py @@ -0,0 +1,73 @@ +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +"""isort:skip_file""" + +import functools +import importlib + + +dependencies = [ + "dataclasses", + "hydra", + "numpy", + "omegaconf", + "regex", + "requests", + "torch", +] + + +# Check for required dependencies and raise a RuntimeError if any are missing. +missing_deps = [] +for dep in dependencies: + try: + importlib.import_module(dep) + except ImportError: + # Hack: the hydra package is provided under the "hydra-core" name in + # pypi. We don't want the user mistakenly calling `pip install hydra` + # since that will install an unrelated package. + if dep == "hydra": + dep = "hydra-core" + missing_deps.append(dep) +if len(missing_deps) > 0: + raise RuntimeError("Missing dependencies: {}".format(", ".join(missing_deps))) + + +# only do fairseq imports after checking for dependencies +from fairseq.hub_utils import ( # noqa; noqa + BPEHubInterface as bpe, + TokenizerHubInterface as tokenizer, +) +from fairseq.models import MODEL_REGISTRY # noqa + + +# torch.hub doesn't build Cython components, so if they are not found then try +# to build them here +try: + import fairseq.data.token_block_utils_fast # noqa +except ImportError: + try: + import cython # noqa + import os + from setuptools import sandbox + + sandbox.run_setup( + os.path.join(os.path.dirname(__file__), "setup.py"), + ["build_ext", "--inplace"], + ) + except ImportError: + print( + "Unable to build Cython components. Please make sure Cython is " + "installed if the torch.hub model you are loading depends on it." + ) + + +# automatically expose models defined in FairseqModel::hub_models +for _model_type, _cls in MODEL_REGISTRY.items(): + for model_name in _cls.hub_models().keys(): + globals()[model_name] = functools.partial( + _cls.from_pretrained, + model_name, + ) diff --git a/PyTorch/NLP/new-Transformer/pyproject.toml b/PyTorch/NLP/new-Transformer/pyproject.toml new file mode 100644 index 00000000..6d1b4c5b --- /dev/null +++ b/PyTorch/NLP/new-Transformer/pyproject.toml @@ -0,0 +1,3 @@ +[build-system] +requires = ["setuptools", "wheel", "cython"] +build-backend = "setuptools.build_meta" diff --git a/PyTorch/NLP/new-Transformer/run-fp16.sh b/PyTorch/NLP/new-Transformer/run-fp16.sh new file mode 100644 index 00000000..d3157b55 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/run-fp16.sh @@ -0,0 +1,28 @@ +export HSA_FORCE_FINE_GRAIN_PCIE=1 +export MIOPEN_FIND_MODE=1 +export HIP_VISIBLE_DEVICES=0 +export TOKEN=2560 +export DATA_PATH=~/data/wmt14_en_de_joined_dict +python3 train.py \ + $DATA_PATH \ + --arch transformer_wmt_en_de \ + --share-decoder-input-output-embed \ + --optimizer adam \ + --adam-betas '(0.9, 0.98)' \ + --clip-norm 0.0 \ + --lr 5e-4 \ + --lr-scheduler inverse_sqrt \ + --warmup-updates 4000 \ + --dropout 0.3 \ + --weight-decay 0.0001 \ + --criterion label_smoothed_cross_entropy \ + --label-smoothing 0.1 \ + --max-tokens ${TOKEN} \ + --eval-bleu \ + --eval-bleu-args '{"beam": 5, "max_len_a": 1.2, "max_len_b": 10}' \ + --eval-bleu-detok moses \ + --eval-bleu-remove-bpe \ + --eval-bleu-print-samples \ + --best-checkpoint-metric bleu \ + --maximize-best-checkpoint-metric \ + --max-epoch 1 --fp16 --reset-optimizer diff --git a/PyTorch/NLP/new-Transformer/run.sh b/PyTorch/NLP/new-Transformer/run.sh new file mode 100644 index 00000000..90a95ddd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/run.sh @@ -0,0 +1,32 @@ + +export HSA_FORCE_FINE_GRAIN_PCIE=1 +export MIOPEN_FIND_MODE=1 +export HIP_VISIBLE_DEVICES=0 +export TOKEN=2560 +export DATA_PATH=~/data/wmt14_en_de_joined_dict + +export HIP_LAUNCH_BLOCKING=1 +export ROCBLAS_ATOMICS_MOD=1 +python3 train.py \ + $DATA_PATH \ + --arch transformer_wmt_en_de \ + --share-decoder-input-output-embed \ + --optimizer adam \ + --adam-betas '(0.9, 0.98)' \ + --clip-norm 0.0 \ + --lr 5e-4 \ + --lr-scheduler inverse_sqrt \ + --warmup-updates 4000 \ + --dropout 0.3 \ + --weight-decay 0.0001 \ + --criterion label_smoothed_cross_entropy \ + --label-smoothing 0.1 \ + --max-tokens ${TOKEN} \ + --eval-bleu \ + --eval-bleu-args '{"beam": 5, "max_len_a": 1.2, "max_len_b": 10}' \ + --eval-bleu-detok moses \ + --eval-bleu-remove-bpe \ + --eval-bleu-print-samples \ + --best-checkpoint-metric bleu \ + --maximize-best-checkpoint-metric \ + --max-epoch 1 diff --git a/PyTorch/NLP/new-Transformer/run4-fp16.sh b/PyTorch/NLP/new-Transformer/run4-fp16.sh new file mode 100644 index 00000000..f867f8b8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/run4-fp16.sh @@ -0,0 +1,23 @@ +#!/usr/bin/env bash +#SBATCH -J distribute +#SBATCH -p wzhdtest +#SBATCH -N 1 +#SBARCH -n 32 +#SBATCH --ntasks-per-node=4 +#SBATCH --cpus-per-task=8 +#SBATCH --gres=dcu:4 +set -x +hostfile=./$SLURM_JOB_ID +scontrol show hostnames $SLURM_JOB_NODELIST > ${hostfile} +for i in `cat $hostfile` +do + echo ${i} slots=4 >> `pwd`/hostfile-$SLURM_JOB_ID + ((num_node=${num_node}+1)) +done +num_dcu=$((${num_node}*4)) +echo $num_dcu +nodename=$(cat $hostfile |sed -n "1p") +echo $nodename +dist_url=`echo $nodename | awk '{print $1}'` +export HSA_USERPTR_FOR_PAGED_MEM=0 +mpirun -np ${num_dcu} --hostfile hostfile-$SLURM_JOB_ID single_fp16.sh $dist_url diff --git a/PyTorch/NLP/new-Transformer/run4.sh b/PyTorch/NLP/new-Transformer/run4.sh new file mode 100644 index 00000000..332f6715 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/run4.sh @@ -0,0 +1,23 @@ +#!/usr/bin/env bash +#SBATCH -J distribute +#SBATCH -p wzhdtest +#SBATCH -N 1 +#SBARCH -n 32 +#SBATCH --ntasks-per-node=4 +#SBATCH --cpus-per-task=8 +#SBATCH --gres=dcu:4 +set -x +hostfile=./$SLURM_JOB_ID +scontrol show hostnames $SLURM_JOB_NODELIST > ${hostfile} +for i in `cat $hostfile` +do + echo ${i} slots=4 >> `pwd`/hostfile-$SLURM_JOB_ID + ((num_node=${num_node}+1)) +done +num_dcu=$((${num_node}*4)) +echo $num_dcu +nodename=$(cat $hostfile |sed -n "1p") +echo $nodename +dist_url=`echo $nodename | awk '{print $1}'` +export HSA_USERPTR_FOR_PAGED_MEM=0 +mpirun -np ${num_dcu} --hostfile hostfile-$SLURM_JOB_ID single_process.sh $dist_url diff --git a/PyTorch/NLP/new-Transformer/scripts/__init__.py b/PyTorch/NLP/new-Transformer/scripts/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/PyTorch/NLP/new-Transformer/scripts/average_checkpoints.py b/PyTorch/NLP/new-Transformer/scripts/average_checkpoints.py new file mode 100644 index 00000000..a4711e48 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/average_checkpoints.py @@ -0,0 +1,160 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import argparse +import collections +import os +import re + +import torch +from fairseq.file_io import PathManager + + +def average_checkpoints(inputs): + """Loads checkpoints from inputs and returns a model with averaged weights. + + Args: + inputs: An iterable of string paths of checkpoints to load from. + + Returns: + A dict of string keys mapping to various values. The 'model' key + from the returned dict should correspond to an OrderedDict mapping + string parameter names to torch Tensors. + """ + params_dict = collections.OrderedDict() + params_keys = None + new_state = None + num_models = len(inputs) + + for fpath in inputs: + with PathManager.open(fpath, "rb") as f: + state = torch.load( + f, + map_location=( + lambda s, _: torch.serialization.default_restore_location(s, "cpu") + ), + ) + # Copies over the settings from the first checkpoint + if new_state is None: + new_state = state + + model_params = state["model"] + + model_params_keys = list(model_params.keys()) + if params_keys is None: + params_keys = model_params_keys + elif params_keys != model_params_keys: + raise KeyError( + "For checkpoint {}, expected list of params: {}, " + "but found: {}".format(f, params_keys, model_params_keys) + ) + + for k in params_keys: + p = model_params[k] + if isinstance(p, torch.HalfTensor): + p = p.float() + if k not in params_dict: + params_dict[k] = p.clone() + # NOTE: clone() is needed in case of p is a shared parameter + else: + params_dict[k] += p + + averaged_params = collections.OrderedDict() + for k, v in params_dict.items(): + averaged_params[k] = v + if averaged_params[k].is_floating_point(): + averaged_params[k].div_(num_models) + else: + averaged_params[k] //= num_models + new_state["model"] = averaged_params + return new_state + + +def last_n_checkpoints(paths, n, update_based, upper_bound=None): + assert len(paths) == 1 + path = paths[0] + if update_based: + pt_regexp = re.compile(r"checkpoint_\d+_(\d+)\.pt") + else: + pt_regexp = re.compile(r"checkpoint(\d+)\.pt") + files = PathManager.ls(path) + + entries = [] + for f in files: + m = pt_regexp.fullmatch(f) + if m is not None: + sort_key = int(m.group(1)) + if upper_bound is None or sort_key <= upper_bound: + entries.append((sort_key, m.group(0))) + if len(entries) < n: + raise Exception( + "Found {} checkpoint files but need at least {}", len(entries), n + ) + return [os.path.join(path, x[1]) for x in sorted(entries, reverse=True)[:n]] + + +def main(): + parser = argparse.ArgumentParser( + description="Tool to average the params of input checkpoints to " + "produce a new checkpoint", + ) + # fmt: off + parser.add_argument('--inputs', required=True, nargs='+', + help='Input checkpoint file paths.') + parser.add_argument('--output', required=True, metavar='FILE', + help='Write the new checkpoint containing the averaged weights to this path.') + num_group = parser.add_mutually_exclusive_group() + num_group.add_argument('--num-epoch-checkpoints', type=int, + help='if set, will try to find checkpoints with names checkpoint_xx.pt in the ' + 'path specified by input, and average last this many of them.') + num_group.add_argument('--num-update-checkpoints', type=int, + help='if set, will try to find checkpoints with names checkpoint_ee_xx.pt in the path specified by' + ' input, and average last this many of them.') + parser.add_argument('--checkpoint-upper-bound', type=int, + help='when using --num-epoch-checkpoints, this will set an upper bound on which epoch to use, ' + 'when using --num-update-checkpoints, this will set an upper bound on which update to use' + 'e.g., with --num-epoch-checkpoints=10 --checkpoint-upper-bound=50, checkpoints 41-50 would be' + ' averaged.' + 'e.g., with --num-update-checkpoints=10 --checkpoint-upper-bound=50000, checkpoints 40500-50000 would' + ' be averaged assuming --save-interval-updates 500' + ) + # fmt: on + args = parser.parse_args() + print(args) + + num = None + is_update_based = False + if args.num_update_checkpoints is not None: + num = args.num_update_checkpoints + is_update_based = True + elif args.num_epoch_checkpoints is not None: + num = args.num_epoch_checkpoints + + assert args.checkpoint_upper_bound is None or ( + args.num_epoch_checkpoints is not None + or args.num_update_checkpoints is not None + ), "--checkpoint-upper-bound requires --num-epoch-checkpoints or --num-update-checkpoints" + assert ( + args.num_epoch_checkpoints is None or args.num_update_checkpoints is None + ), "Cannot combine --num-epoch-checkpoints and --num-update-checkpoints" + + if num is not None: + args.inputs = last_n_checkpoints( + args.inputs, + num, + is_update_based, + upper_bound=args.checkpoint_upper_bound, + ) + print("averaging checkpoints: ", args.inputs) + + new_state = average_checkpoints(args.inputs) + with PathManager.open(args.output, "wb") as f: + torch.save(new_state, f) + print("Finished writing averaged checkpoint to {}".format(args.output)) + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/Transformer/scripts/build_sym_alignment.py b/PyTorch/NLP/new-Transformer/scripts/build_sym_alignment.py similarity index 58% rename from PyTorch/NLP/Transformer/scripts/build_sym_alignment.py rename to PyTorch/NLP/new-Transformer/scripts/build_sym_alignment.py index 11f06593..0ca5c18f 100644 --- a/PyTorch/NLP/Transformer/scripts/build_sym_alignment.py +++ b/PyTorch/NLP/new-Transformer/scripts/build_sym_alignment.py @@ -1,11 +1,7 @@ -# Copyright (c) 2017-present, Facebook, Inc. -# All rights reserved. +# Copyright (c) Facebook, Inc. and its affiliates. # -# This source code is licensed under the license found in the LICENSE file in -# the root directory of this source tree. An additional grant of patent rights -# can be found in the PATENTS file in the same directory. -# - +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. """ Use this script in order to build symmetric alignments for your translation dataset. @@ -31,7 +27,8 @@ from itertools import zip_longest def main(): - parser = argparse.ArgumentParser(description='symmetric alignment builer') + parser = argparse.ArgumentParser(description="symmetric alignment builer") + # fmt: off parser.add_argument('--fast_align_dir', help='path to fast_align build directory') parser.add_argument('--mosesdecoder_dir', @@ -47,42 +44,43 @@ def main(): 'in the target language') parser.add_argument('--output_dir', help='output directory') + # fmt: on args = parser.parse_args() - fast_align_bin = os.path.join(args.fast_align_dir, 'fast_align') - symal_bin = os.path.join(args.mosesdecoder_dir, 'bin', 'symal') + fast_align_bin = os.path.join(args.fast_align_dir, "fast_align") + symal_bin = os.path.join(args.mosesdecoder_dir, "bin", "symal") sym_fast_align_bin = os.path.join( - args.mosesdecoder_dir, 'scripts', 'ems', - 'support', 'symmetrize-fast-align.perl') + args.mosesdecoder_dir, "scripts", "ems", "support", "symmetrize-fast-align.perl" + ) # create joined file - joined_file = os.path.join(args.output_dir, 'text.joined') - with open(args.source_file, 'r') as src, open(args.target_file, 'r') as tgt: - with open(joined_file, 'w') as joined: + joined_file = os.path.join(args.output_dir, "text.joined") + with open(args.source_file, "r", encoding="utf-8") as src, open( + args.target_file, "r", encoding="utf-8" + ) as tgt: + with open(joined_file, "w", encoding="utf-8") as joined: for s, t in zip_longest(src, tgt): - print('{} ||| {}'.format(s.strip(), t.strip()), file=joined) + print("{} ||| {}".format(s.strip(), t.strip()), file=joined) - bwd_align_file = os.path.join(args.output_dir, 'align.backward') + bwd_align_file = os.path.join(args.output_dir, "align.backward") # run forward alignment - fwd_align_file = os.path.join(args.output_dir, 'align.forward') - fwd_fast_align_cmd = '{FASTALIGN} -i {JOINED} -d -o -v > {FWD}'.format( - FASTALIGN=fast_align_bin, - JOINED=joined_file, - FWD=fwd_align_file) + fwd_align_file = os.path.join(args.output_dir, "align.forward") + fwd_fast_align_cmd = "{FASTALIGN} -i {JOINED} -d -o -v > {FWD}".format( + FASTALIGN=fast_align_bin, JOINED=joined_file, FWD=fwd_align_file + ) assert os.system(fwd_fast_align_cmd) == 0 # run backward alignment - bwd_align_file = os.path.join(args.output_dir, 'align.backward') - bwd_fast_align_cmd = '{FASTALIGN} -i {JOINED} -d -o -v -r > {BWD}'.format( - FASTALIGN=fast_align_bin, - JOINED=joined_file, - BWD=bwd_align_file) + bwd_align_file = os.path.join(args.output_dir, "align.backward") + bwd_fast_align_cmd = "{FASTALIGN} -i {JOINED} -d -o -v -r > {BWD}".format( + FASTALIGN=fast_align_bin, JOINED=joined_file, BWD=bwd_align_file + ) assert os.system(bwd_fast_align_cmd) == 0 # run symmetrization - sym_out_file = os.path.join(args.output_dir, 'aligned') - sym_cmd = '{SYMFASTALIGN} {FWD} {BWD} {SRC} {TGT} {OUT} {HEURISTIC} {SYMAL}'.format( + sym_out_file = os.path.join(args.output_dir, "aligned") + sym_cmd = "{SYMFASTALIGN} {FWD} {BWD} {SRC} {TGT} {OUT} {HEURISTIC} {SYMAL}".format( SYMFASTALIGN=sym_fast_align_bin, FWD=fwd_align_file, BWD=bwd_align_file, @@ -90,10 +88,10 @@ def main(): TGT=args.target_file, OUT=sym_out_file, HEURISTIC=args.sym_heuristic, - SYMAL=symal_bin + SYMAL=symal_bin, ) assert os.system(sym_cmd) == 0 -if __name__ == '__main__': +if __name__ == "__main__": main() diff --git a/PyTorch/NLP/new-Transformer/scripts/compare_namespaces.py b/PyTorch/NLP/new-Transformer/scripts/compare_namespaces.py new file mode 100644 index 00000000..bc24db62 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/compare_namespaces.py @@ -0,0 +1,46 @@ +#!/usr/bin/env python +"""Helper script to compare two argparse.Namespace objects.""" + +from argparse import Namespace # noqa + + +def main(): + + ns1 = eval(input("Namespace 1: ")) + ns2 = eval(input("Namespace 2: ")) + + def keys(ns): + ks = set() + for k in dir(ns): + if not k.startswith("_"): + ks.add(k) + return ks + + k1 = keys(ns1) + k2 = keys(ns2) + + def print_keys(ks, ns1, ns2=None): + for k in ks: + if ns2 is None: + print("{}\t{}".format(k, getattr(ns1, k, None))) + else: + print( + "{}\t{}\t{}".format(k, getattr(ns1, k, None), getattr(ns2, k, None)) + ) + + print("Keys unique to namespace 1:") + print_keys(k1 - k2, ns1) + print() + + print("Keys unique to namespace 2:") + print_keys(k2 - k1, ns2) + print() + + print("Overlapping keys with different values:") + ks = [k for k in k1 & k2 if getattr(ns1, k, "None") != getattr(ns2, k, "None")] + print_keys(ks, ns1, ns2) + print() + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/new-Transformer/scripts/compound_split_bleu.sh b/PyTorch/NLP/new-Transformer/scripts/compound_split_bleu.sh new file mode 100644 index 00000000..1972fddc --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/compound_split_bleu.sh @@ -0,0 +1,20 @@ +#!/bin/bash + +if [ $# -ne 1 ]; then + echo "usage: $0 GENERATE_PY_OUTPUT" + exit 1 +fi + +GEN=$1 + +SYS=$GEN.sys +REF=$GEN.ref + +if [ $(tail -n 1 $GEN | grep BLEU | wc -l) -ne 1 ]; then + echo "not done generating" + exit +fi + +grep ^H $GEN | awk -F '\t' '{print $NF}' | perl -ple 's{(\S)-(\S)}{$1 ##AT##-##AT## $2}g' > $SYS +grep ^T $GEN | cut -f2- | perl -ple 's{(\S)-(\S)}{$1 ##AT##-##AT## $2}g' > $REF +fairseq-score --sys $SYS --ref $REF diff --git a/PyTorch/NLP/new-Transformer/scripts/constraints/extract.py b/PyTorch/NLP/new-Transformer/scripts/constraints/extract.py new file mode 100644 index 00000000..437b3738 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/constraints/extract.py @@ -0,0 +1,90 @@ +#!/usr/bin/env python3 +# +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +"""Extracts random constraints from reference files.""" + +import argparse +import random +import sys + + +def get_phrase(words, index, length): + assert index < len(words) - length + 1 + phr = " ".join(words[index : index + length]) + for i in range(index, index + length): + words.pop(index) + return phr + + +def main(args): + + if args.seed: + random.seed(args.seed) + + for line in sys.stdin: + constraints = [] + + def add_constraint(constraint): + constraints.append(constraint) + + source = line.rstrip() + if "\t" in line: + source, target = line.split("\t") + if args.add_sos: + target = f" {target}" + if args.add_eos: + target = f"{target} " + + if len(target.split()) >= args.len: + words = [target] + + num = args.number + + choices = {} + for i in range(num): + if len(words) == 0: + break + segmentno = random.choice(range(len(words))) + segment = words.pop(segmentno) + tokens = segment.split() + phrase_index = random.choice(range(len(tokens))) + choice = " ".join( + tokens[phrase_index : min(len(tokens), phrase_index + args.len)] + ) + for j in range( + phrase_index, min(len(tokens), phrase_index + args.len) + ): + tokens.pop(phrase_index) + if phrase_index > 0: + words.append(" ".join(tokens[0:phrase_index])) + if phrase_index + 1 < len(tokens): + words.append(" ".join(tokens[phrase_index:])) + choices[target.find(choice)] = choice + + # mask out with spaces + target = target.replace(choice, " " * len(choice), 1) + + for key in sorted(choices.keys()): + add_constraint(choices[key]) + + print(source, *constraints, sep="\t") + + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + parser.add_argument("--number", "-n", type=int, default=1, help="number of phrases") + parser.add_argument("--len", "-l", type=int, default=1, help="phrase length") + parser.add_argument( + "--add-sos", default=False, action="store_true", help="add token" + ) + parser.add_argument( + "--add-eos", default=False, action="store_true", help="add token" + ) + parser.add_argument("--seed", "-s", default=0, type=int) + args = parser.parse_args() + + main(args) diff --git a/PyTorch/NLP/new-Transformer/scripts/constraints/validate.py b/PyTorch/NLP/new-Transformer/scripts/constraints/validate.py new file mode 100644 index 00000000..d531ad9f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/constraints/validate.py @@ -0,0 +1,34 @@ +#!/usr/bin/env python3 +# +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import sys + + +"""Reads in a fairseq output file, and verifies that the constraints +(C- lines) are present in the output (the first H- line). Assumes that +constraints are listed prior to the first hypothesis. +""" + +constraints = [] +found = 0 +total = 0 +for line in sys.stdin: + if line.startswith("C-"): + constraints.append(line.rstrip().split("\t")[1]) + elif line.startswith("H-"): + text = line.split("\t")[2] + + for constraint in constraints: + total += 1 + if constraint in text: + found += 1 + else: + print(f"No {constraint} in {text}", file=sys.stderr) + + constraints = [] + +print(f"Found {found} / {total} = {100 * found / total:.1f}%") diff --git a/PyTorch/NLP/new-Transformer/scripts/convert_dictionary.lua b/PyTorch/NLP/new-Transformer/scripts/convert_dictionary.lua new file mode 100644 index 00000000..14ee8c99 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/convert_dictionary.lua @@ -0,0 +1,34 @@ +-- Copyright (c) Facebook, Inc. and its affiliates. +-- +-- This source code is licensed under the MIT license found in the +-- LICENSE file in the root directory of this source tree. +-- +-- Usage: convert_dictionary.lua +require 'fairseq' +require 'torch' +require 'paths' + +if #arg < 1 then + print('usage: convert_dictionary.lua ') + os.exit(1) +end +if not paths.filep(arg[1]) then + print('error: file does not exit: ' .. arg[1]) + os.exit(1) +end + +dict = torch.load(arg[1]) +dst = paths.basename(arg[1]):gsub('.th7', '.txt') +assert(dst:match('.txt$')) + +f = io.open(dst, 'w') +for idx, symbol in ipairs(dict.index_to_symbol) do + if idx > dict.cutoff then + break + end + f:write(symbol) + f:write(' ') + f:write(dict.index_to_freq[idx]) + f:write('\n') +end +f:close() diff --git a/PyTorch/NLP/new-Transformer/scripts/convert_model.lua b/PyTorch/NLP/new-Transformer/scripts/convert_model.lua new file mode 100644 index 00000000..61b92139 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/convert_model.lua @@ -0,0 +1,108 @@ +-- Copyright (c) Facebook, Inc. and its affiliates. +-- +-- This source code is licensed under the MIT license found in the +-- LICENSE file in the root directory of this source tree. +-- +-- Usage: convert_model.lua +require 'torch' +local fairseq = require 'fairseq' + +model = torch.load(arg[1]) + +function find_weight_norm(container, module) + for _, wn in ipairs(container:listModules()) do + if torch.type(wn) == 'nn.WeightNorm' and wn.modules[1] == module then + return wn + end + end +end + +function push_state(dict, key, module) + if torch.type(module) == 'nn.Linear' then + local wn = find_weight_norm(model.module, module) + assert(wn) + dict[key .. '.weight_v'] = wn.v:float() + dict[key .. '.weight_g'] = wn.g:float() + elseif torch.type(module) == 'nn.TemporalConvolutionTBC' then + local wn = find_weight_norm(model.module, module) + assert(wn) + local v = wn.v:float():view(wn.viewOut):transpose(2, 3) + dict[key .. '.weight_v'] = v + dict[key .. '.weight_g'] = wn.g:float():view(module.weight:size(3), 1, 1) + else + dict[key .. '.weight'] = module.weight:float() + end + if module.bias then + dict[key .. '.bias'] = module.bias:float() + end +end + +encoder_dict = {} +decoder_dict = {} +combined_dict = {} + +function encoder_state(encoder) + luts = encoder:findModules('nn.LookupTable') + push_state(encoder_dict, 'embed_tokens', luts[1]) + push_state(encoder_dict, 'embed_positions', luts[2]) + + fcs = encoder:findModules('nn.Linear') + assert(#fcs >= 2) + local nInputPlane = fcs[1].weight:size(1) + push_state(encoder_dict, 'fc1', table.remove(fcs, 1)) + push_state(encoder_dict, 'fc2', table.remove(fcs, #fcs)) + + for i, module in ipairs(encoder:findModules('nn.TemporalConvolutionTBC')) do + push_state(encoder_dict, 'convolutions.' .. tostring(i - 1), module) + if nInputPlane ~= module.weight:size(3) / 2 then + push_state(encoder_dict, 'projections.' .. tostring(i - 1), table.remove(fcs, 1)) + end + nInputPlane = module.weight:size(3) / 2 + end + assert(#fcs == 0) +end + +function decoder_state(decoder) + luts = decoder:findModules('nn.LookupTable') + push_state(decoder_dict, 'embed_tokens', luts[1]) + push_state(decoder_dict, 'embed_positions', luts[2]) + + fcs = decoder:findModules('nn.Linear') + local nInputPlane = fcs[1].weight:size(1) + push_state(decoder_dict, 'fc1', table.remove(fcs, 1)) + push_state(decoder_dict, 'fc2', fcs[#fcs - 1]) + push_state(decoder_dict, 'fc3', fcs[#fcs]) + + table.remove(fcs, #fcs) + table.remove(fcs, #fcs) + + for i, module in ipairs(decoder:findModules('nn.TemporalConvolutionTBC')) do + if nInputPlane ~= module.weight:size(3) / 2 then + push_state(decoder_dict, 'projections.' .. tostring(i - 1), table.remove(fcs, 1)) + end + nInputPlane = module.weight:size(3) / 2 + + local prefix = 'attention.' .. tostring(i - 1) + push_state(decoder_dict, prefix .. '.in_projection', table.remove(fcs, 1)) + push_state(decoder_dict, prefix .. '.out_projection', table.remove(fcs, 1)) + push_state(decoder_dict, 'convolutions.' .. tostring(i - 1), module) + end + assert(#fcs == 0) +end + + +_encoder = model.module.modules[2] +_decoder = model.module.modules[3] + +encoder_state(_encoder) +decoder_state(_decoder) + +for k, v in pairs(encoder_dict) do + combined_dict['encoder.' .. k] = v +end +for k, v in pairs(decoder_dict) do + combined_dict['decoder.' .. k] = v +end + + +torch.save('state_dict.t7', combined_dict) diff --git a/PyTorch/NLP/new-Transformer/scripts/count_docs.py b/PyTorch/NLP/new-Transformer/scripts/count_docs.py new file mode 100644 index 00000000..58d85af8 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/count_docs.py @@ -0,0 +1,58 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Count the number of documents and average number of lines and tokens per +document in a large file. Documents should be separated by a single empty line. +""" + +import argparse +import gzip +import sys + +import numpy as np + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument("input") + parser.add_argument("--gzip", action="store_true") + args = parser.parse_args() + + def gopen(): + if args.gzip: + return gzip.open(args.input, "r") + else: + return open(args.input, "r", encoding="utf-8") + + num_lines = [] + num_toks = [] + with gopen() as h: + num_docs = 1 + num_lines_in_doc = 0 + num_toks_in_doc = 0 + for i, line in enumerate(h): + if len(line.strip()) == 0: # empty line indicates new document + num_docs += 1 + num_lines.append(num_lines_in_doc) + num_toks.append(num_toks_in_doc) + num_lines_in_doc = 0 + num_toks_in_doc = 0 + else: + num_lines_in_doc += 1 + num_toks_in_doc += len(line.rstrip().split()) + if i % 1000000 == 0: + print(i, file=sys.stderr, end="", flush=True) + elif i % 100000 == 0: + print(".", file=sys.stderr, end="", flush=True) + print(file=sys.stderr, flush=True) + + print("found {} docs".format(num_docs)) + print("average num lines per doc: {}".format(np.mean(num_lines))) + print("average num toks per doc: {}".format(np.mean(num_toks))) + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/new-Transformer/scripts/read_binarized.py b/PyTorch/NLP/new-Transformer/scripts/read_binarized.py new file mode 100644 index 00000000..a414095d --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/read_binarized.py @@ -0,0 +1,48 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import argparse + +from fairseq.data import Dictionary, data_utils, indexed_dataset + + +def get_parser(): + parser = argparse.ArgumentParser( + description="writes text from binarized file to stdout" + ) + # fmt: off + parser.add_argument('--dataset-impl', help='dataset implementation', + choices=indexed_dataset.get_available_dataset_impl()) + parser.add_argument('--dict', metavar='FP', help='dictionary containing known words', default=None) + parser.add_argument('--input', metavar='FP', required=True, help='binarized file to read') + # fmt: on + + return parser + + +def main(): + parser = get_parser() + args = parser.parse_args() + + dictionary = Dictionary.load(args.dict) if args.dict is not None else None + dataset = data_utils.load_indexed_dataset( + args.input, + dictionary, + dataset_impl=args.dataset_impl, + default="lazy", + ) + + for tensor_line in dataset: + if dictionary is None: + line = " ".join([str(int(x)) for x in tensor_line]) + else: + line = dictionary.string(tensor_line) + + print(line) + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/new-Transformer/scripts/rm_pt.py b/PyTorch/NLP/new-Transformer/scripts/rm_pt.py new file mode 100644 index 00000000..6cd063d2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/rm_pt.py @@ -0,0 +1,141 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import argparse +import os +import re +import shutil +import sys + + +pt_regexp = re.compile(r"checkpoint(\d+|_\d+_\d+|_[a-z]+)\.pt") +pt_regexp_epoch_based = re.compile(r"checkpoint(\d+)\.pt") +pt_regexp_update_based = re.compile(r"checkpoint_\d+_(\d+)\.pt") + + +def parse_checkpoints(files): + entries = [] + for f in files: + m = pt_regexp_epoch_based.fullmatch(f) + if m is not None: + entries.append((int(m.group(1)), m.group(0))) + else: + m = pt_regexp_update_based.fullmatch(f) + if m is not None: + entries.append((int(m.group(1)), m.group(0))) + return entries + + +def last_n_checkpoints(files, n): + entries = parse_checkpoints(files) + return [x[1] for x in sorted(entries, reverse=True)[:n]] + + +def every_n_checkpoints(files, n): + entries = parse_checkpoints(files) + return [x[1] for x in sorted(sorted(entries)[::-n])] + + +def main(): + parser = argparse.ArgumentParser( + description=( + "Recursively delete checkpoint files from `root_dir`, " + "but preserve checkpoint_best.pt and checkpoint_last.pt" + ) + ) + parser.add_argument("root_dirs", nargs="*") + parser.add_argument( + "--save-last", type=int, default=0, help="number of last checkpoints to save" + ) + parser.add_argument( + "--save-every", type=int, default=0, help="interval of checkpoints to save" + ) + parser.add_argument( + "--preserve-test", + action="store_true", + help="preserve checkpoints in dirs that start with test_ prefix (default: delete them)", + ) + parser.add_argument( + "--delete-best", action="store_true", help="delete checkpoint_best.pt" + ) + parser.add_argument( + "--delete-last", action="store_true", help="delete checkpoint_last.pt" + ) + parser.add_argument( + "--no-dereference", action="store_true", help="don't dereference symlinks" + ) + args = parser.parse_args() + + files_to_desymlink = [] + files_to_preserve = [] + files_to_delete = [] + for root_dir in args.root_dirs: + for root, _subdirs, files in os.walk(root_dir): + if args.save_last > 0: + to_save = last_n_checkpoints(files, args.save_last) + else: + to_save = [] + if args.save_every > 0: + to_save += every_n_checkpoints(files, args.save_every) + for file in files: + if not pt_regexp.fullmatch(file): + continue + full_path = os.path.join(root, file) + if ( + not os.path.basename(root).startswith("test_") or args.preserve_test + ) and ( + (file == "checkpoint_last.pt" and not args.delete_last) + or (file == "checkpoint_best.pt" and not args.delete_best) + or file in to_save + ): + if os.path.islink(full_path) and not args.no_dereference: + files_to_desymlink.append(full_path) + else: + files_to_preserve.append(full_path) + else: + files_to_delete.append(full_path) + + if len(files_to_desymlink) == 0 and len(files_to_delete) == 0: + print("Nothing to do.") + sys.exit(0) + + files_to_desymlink = sorted(files_to_desymlink) + files_to_preserve = sorted(files_to_preserve) + files_to_delete = sorted(files_to_delete) + + print("Operations to perform (in order):") + if len(files_to_desymlink) > 0: + for file in files_to_desymlink: + print(" - preserve (and dereference symlink): " + file) + if len(files_to_preserve) > 0: + for file in files_to_preserve: + print(" - preserve: " + file) + if len(files_to_delete) > 0: + for file in files_to_delete: + print(" - delete: " + file) + while True: + resp = input("Continue? (Y/N): ") + if resp.strip().lower() == "y": + break + elif resp.strip().lower() == "n": + sys.exit(0) + + print("Executing...") + if len(files_to_desymlink) > 0: + for file in files_to_desymlink: + realpath = os.path.realpath(file) + print("rm " + file) + os.remove(file) + print("cp {} {}".format(realpath, file)) + shutil.copyfile(realpath, file) + if len(files_to_delete) > 0: + for file in files_to_delete: + print("rm " + file) + os.remove(file) + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/new-Transformer/scripts/sacrebleu.sh b/PyTorch/NLP/new-Transformer/scripts/sacrebleu.sh new file mode 100644 index 00000000..c10bf2b7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/sacrebleu.sh @@ -0,0 +1,27 @@ +#!/bin/bash + +if [ $# -ne 4 ]; then + echo "usage: $0 TESTSET SRCLANG TGTLANG GEN" + exit 1 +fi + +TESTSET=$1 +SRCLANG=$2 +TGTLANG=$3 + +GEN=$4 + +if ! command -v sacremoses &> /dev/null +then + echo "sacremoses could not be found, please install with: pip install sacremoses" + exit +fi + +grep ^H $GEN \ +| sed 's/^H\-//' \ +| sort -n -k 1 \ +| cut -f 3 \ +| sacremoses detokenize \ +> $GEN.sorted.detok + +sacrebleu --test-set $TESTSET --language-pair "${SRCLANG}-${TGTLANG}" < $GEN.sorted.detok diff --git a/PyTorch/NLP/new-Transformer/scripts/shard_docs.py b/PyTorch/NLP/new-Transformer/scripts/shard_docs.py new file mode 100644 index 00000000..97232c3c --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/shard_docs.py @@ -0,0 +1,54 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Split a large file into shards while respecting document boundaries. Documents +should be separated by a single empty line. +""" + +import argparse +import contextlib + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument("input") + parser.add_argument("--num-shards", type=int) + args = parser.parse_args() + + assert args.num_shards is not None and args.num_shards > 1 + + with open(args.input, "r", encoding="utf-8") as h: + with contextlib.ExitStack() as stack: + outputs = [ + stack.enter_context( + open(args.input + ".shard" + str(i), "w", encoding="utf-8") + ) + for i in range(args.num_shards) + ] + + doc = [] + first_doc = [True] * args.num_shards + + def output_doc(i): + if not first_doc[i]: + outputs[i].write("\n") + first_doc[i] = False + for line in doc: + outputs[i].write(line) + doc.clear() + + num_docs = 0 + for line in h: + if line.strip() == "": # empty line indicates new document + output_doc(num_docs % args.num_shards) + num_docs += 1 + else: + doc.append(line) + output_doc(num_docs % args.num_shards) + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/new-Transformer/scripts/split_train_valid_docs.py b/PyTorch/NLP/new-Transformer/scripts/split_train_valid_docs.py new file mode 100644 index 00000000..ff159785 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/split_train_valid_docs.py @@ -0,0 +1,86 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Split a large file into a train and valid set while respecting document +boundaries. Documents should be separated by a single empty line. +""" + +import argparse +import random +import sys + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument("input") + parser.add_argument("sample_output", help="train output file") + parser.add_argument("remainder_output", help="valid output file") + parser.add_argument("-k", type=int, help="remainder size") + parser.add_argument( + "--lines", action="store_true", help="split lines instead of docs" + ) + args = parser.parse_args() + + assert args.k is not None + + sample = [] + remainder = [] + num_docs = [0] + + def update_sample(doc): + if len(sample) < args.k: + sample.append(doc.copy()) + else: + i = num_docs[0] + j = random.randrange(i + 1) + if j < args.k: + remainder.append(sample[j]) + sample[j] = doc.copy() + else: + remainder.append(doc.copy()) + num_docs[0] += 1 + doc.clear() + + with open(args.input, "r", encoding="utf-8") as h: + doc = [] + for i, line in enumerate(h): + if line.strip() == "": # empty line indicates new document + update_sample(doc) + else: + doc.append(line) + if args.lines: + update_sample(doc) + if i % 1000000 == 0: + print(i, file=sys.stderr, end="", flush=True) + elif i % 100000 == 0: + print(".", file=sys.stderr, end="", flush=True) + if len(doc) > 0: + update_sample(doc) + print(file=sys.stderr, flush=True) + + assert len(sample) == args.k + + with open(args.sample_output, "w", encoding="utf-8") as out: + first = True + for doc in sample: + if not first and not args.lines: + out.write("\n") + first = False + for line in doc: + out.write(line) + + with open(args.remainder_output, "w", encoding="utf-8") as out: + first = True + for doc in remainder: + if not first and not args.lines: + out.write("\n") + first = False + for line in doc: + out.write(line) + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/new-Transformer/scripts/spm_decode.py b/PyTorch/NLP/new-Transformer/scripts/spm_decode.py new file mode 100644 index 00000000..7d7b68b2 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/spm_decode.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python +# Copyright (c) Facebook, Inc. and its affiliates. +# All rights reserved. +# +# This source code is licensed under the license found in the +# LICENSE file in the root directory of this source tree. + +from __future__ import absolute_import, division, print_function, unicode_literals + +import argparse + +import sentencepiece as spm + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument( + "--model", required=True, help="sentencepiece model to use for decoding" + ) + parser.add_argument("--input", required=True, help="input file to decode") + parser.add_argument("--input_format", choices=["piece", "id"], default="piece") + args = parser.parse_args() + + sp = spm.SentencePieceProcessor() + sp.Load(args.model) + + if args.input_format == "piece": + + def decode(input): + return "".join(sp.DecodePieces(input)) + + elif args.input_format == "id": + + def decode(input): + return "".join(sp.DecodeIds(input)) + + else: + raise NotImplementedError + + def tok2int(tok): + # remap reference-side (represented as <>) to 0 + return int(tok) if tok != "<>" else 0 + + with open(args.input, "r", encoding="utf-8") as h: + for line in h: + if args.input_format == "id": + print(decode(list(map(tok2int, line.rstrip().split())))) + elif args.input_format == "piece": + print(decode(line.rstrip().split())) + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/new-Transformer/scripts/spm_encode.py b/PyTorch/NLP/new-Transformer/scripts/spm_encode.py new file mode 100644 index 00000000..f91e0bb7 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/spm_encode.py @@ -0,0 +1,119 @@ +#!/usr/bin/env python +# Copyright (c) Facebook, Inc. and its affiliates. +# All rights reserved. +# +# This source code is licensed under the license found in the +# LICENSE file in the root directory of this source tree. + +from __future__ import absolute_import, division, print_function, unicode_literals + +import argparse +import contextlib +import sys + +import sentencepiece as spm + + +def main(): + parser = argparse.ArgumentParser() + parser.add_argument( + "--model", required=True, help="sentencepiece model to use for encoding" + ) + parser.add_argument( + "--inputs", nargs="+", default=["-"], help="input files to filter/encode" + ) + parser.add_argument( + "--outputs", nargs="+", default=["-"], help="path to save encoded outputs" + ) + parser.add_argument("--output_format", choices=["piece", "id"], default="piece") + parser.add_argument( + "--min-len", + type=int, + metavar="N", + help="filter sentence pairs with fewer than N tokens", + ) + parser.add_argument( + "--max-len", + type=int, + metavar="N", + help="filter sentence pairs with more than N tokens", + ) + args = parser.parse_args() + + assert len(args.inputs) == len( + args.outputs + ), "number of input and output paths should match" + + sp = spm.SentencePieceProcessor() + sp.Load(args.model) + + if args.output_format == "piece": + + def encode(input): + return sp.EncodeAsPieces(input) + + elif args.output_format == "id": + + def encode(input): + return list(map(str, sp.EncodeAsIds(input))) + + else: + raise NotImplementedError + + if args.min_len is not None or args.max_len is not None: + + def valid(line): + return (args.min_len is None or len(line) >= args.min_len) and ( + args.max_len is None or len(line) <= args.max_len + ) + + else: + + def valid(lines): + return True + + with contextlib.ExitStack() as stack: + inputs = [ + stack.enter_context(open(input, "r", encoding="utf-8")) + if input != "-" + else sys.stdin + for input in args.inputs + ] + outputs = [ + stack.enter_context(open(output, "w", encoding="utf-8")) + if output != "-" + else sys.stdout + for output in args.outputs + ] + + stats = { + "num_empty": 0, + "num_filtered": 0, + } + + def encode_line(line): + line = line.strip() + if len(line) > 0: + line = encode(line) + if valid(line): + return line + else: + stats["num_filtered"] += 1 + else: + stats["num_empty"] += 1 + return None + + for i, lines in enumerate(zip(*inputs), start=1): + enc_lines = list(map(encode_line, lines)) + if not any(enc_line is None for enc_line in enc_lines): + for enc_line, output_h in zip(enc_lines, outputs): + print(" ".join(enc_line), file=output_h) + if i % 10000 == 0: + print("processed {} lines".format(i), file=sys.stderr) + + print("skipped {} empty lines".format(stats["num_empty"]), file=sys.stderr) + print("filtered {} lines".format(stats["num_filtered"]), file=sys.stderr) + + +if __name__ == "__main__": + main() diff --git a/PyTorch/NLP/new-Transformer/scripts/spm_train.py b/PyTorch/NLP/new-Transformer/scripts/spm_train.py new file mode 100644 index 00000000..9db668fd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/spm_train.py @@ -0,0 +1,16 @@ +#!/usr/bin/env python +# Copyright (c) Facebook, Inc. and its affiliates. +# All rights reserved. +# +# This source code is licensed under the license found in the +# LICENSE file in the root directory of this source tree. + +from __future__ import absolute_import, division, print_function, unicode_literals + +import sys + +import sentencepiece as spm + + +if __name__ == "__main__": + spm.SentencePieceTrainer.Train(" ".join(sys.argv[1:])) diff --git a/PyTorch/NLP/new-Transformer/scripts/test_fsdp.sh b/PyTorch/NLP/new-Transformer/scripts/test_fsdp.sh new file mode 100644 index 00000000..1f428a03 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/scripts/test_fsdp.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +rm -rf fsdp_dummy +mkdir -p fsdp_dummy +CUDA_VISIBLE_DEVICES=0,1,2,3 fairseq-train /private/home/sshleifer/data-bin/stories_mmap \ + --ddp-backend fully_sharded --fp16 --fp16-init-scale 4 \ + --cpu-offload --checkpoint-activations \ + --task language_modeling --tokens-per-sample 256 --batch-size 8 \ + --arch transformer_lm_gpt2_tiny \ + --optimizer cpu_adam --adam-betas "(0.9,0.98)" \ + --lr 0.0001 --lr-scheduler polynomial_decay --warmup-updates 5 --total-num-update 10 \ + --max-update 5 --log-format json --log-interval 1 \ + --save-interval-updates 5 --save-dir fsdp_dummy --disable-validation \ + --restore-file x.pt "$@" + +# Now we try to load the checkpoint +CUDA_VISIBLE_DEVICES=0,1 fairseq-train /private/home/sshleifer/data-bin/stories_mmap \ + --ddp-backend fully_sharded --fp16 --fp16-init-scale 4 \ + --cpu-offload --checkpoint-activations \ + --task language_modeling --tokens-per-sample 256 --batch-size 8 \ + --arch transformer_lm_gpt2_tiny \ + --optimizer cpu_adam --adam-betas "(0.9,0.98)" \ + --lr 0.0001 --lr-scheduler polynomial_decay --warmup-updates 5 --total-num-update 10 \ + --max-update 2 --log-format json --log-interval 1 \ + --save-interval-updates 2 --save-dir fsdp_dummy diff --git a/PyTorch/NLP/new-Transformer/setup.cfg b/PyTorch/NLP/new-Transformer/setup.cfg new file mode 100644 index 00000000..3fa679dd --- /dev/null +++ b/PyTorch/NLP/new-Transformer/setup.cfg @@ -0,0 +1,4 @@ +[flake8] +max-line-length = 127 +extend-ignore = E203, W503 +extend-exclude = fairseq/model_parallel/megatron diff --git a/PyTorch/NLP/new-Transformer/setup.py b/PyTorch/NLP/new-Transformer/setup.py new file mode 100644 index 00000000..cb6f0804 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/setup.py @@ -0,0 +1,284 @@ +#!/usr/bin/env python3 +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. + +import os +import subprocess +import sys + +from setuptools import Extension, find_packages, setup + +if sys.version_info < (3, 6): + sys.exit("Sorry, Python >= 3.6 is required for fairseq.") + + +def write_version_py(): + with open(os.path.join("fairseq", "version.txt")) as f: + version = f.read().strip() + + # append latest commit hash to version string + try: + sha = ( + subprocess.check_output(["git", "rev-parse", "HEAD"]) + .decode("ascii") + .strip() + ) + version += "+" + sha[:7] + except Exception: + pass + + # write version info to fairseq/version.py + with open(os.path.join("fairseq", "version.py"), "w") as f: + f.write('__version__ = "{}"\n'.format(version)) + return version + + +version = write_version_py() + + +with open("README.md") as f: + readme = f.read() + + +if sys.platform == "darwin": + extra_compile_args = ["-stdlib=libc++", "-O3"] +else: + extra_compile_args = ["-std=c++11", "-O3"] + + +class NumpyExtension(Extension): + """Source: https://stackoverflow.com/a/54128391""" + + def __init__(self, *args, **kwargs): + self.__include_dirs = [] + super().__init__(*args, **kwargs) + + @property + def include_dirs(self): + import numpy + + return self.__include_dirs + [numpy.get_include()] + + @include_dirs.setter + def include_dirs(self, dirs): + self.__include_dirs = dirs + + +extensions = [ + Extension( + "fairseq.libbleu", + sources=[ + "fairseq/clib/libbleu/libbleu.cpp", + "fairseq/clib/libbleu/module.cpp", + ], + extra_compile_args=extra_compile_args, + ), + NumpyExtension( + "fairseq.data.data_utils_fast", + sources=["fairseq/data/data_utils_fast.pyx"], + language="c++", + extra_compile_args=extra_compile_args, + ), + NumpyExtension( + "fairseq.data.token_block_utils_fast", + sources=["fairseq/data/token_block_utils_fast.pyx"], + language="c++", + extra_compile_args=extra_compile_args, + ), +] + + +cmdclass = {} + + +try: + # torch is not available when generating docs + from torch.utils import cpp_extension + + extensions.extend( + [ + cpp_extension.CppExtension( + "fairseq.libbase", + sources=[ + "fairseq/clib/libbase/balanced_assignment.cpp", + ], + ) + ] + ) + + extensions.extend( + [ + cpp_extension.CppExtension( + "fairseq.libnat", + sources=[ + "fairseq/clib/libnat/edit_dist.cpp", + ], + ), + cpp_extension.CppExtension( + "alignment_train_cpu_binding", + sources=[ + "examples/operators/alignment_train_cpu.cpp", + ], + ), + ] + ) + if "CUDA_HOME" in os.environ: + extensions.extend( + [ + cpp_extension.CppExtension( + "fairseq.libnat_cuda", + sources=[ + "fairseq/clib/libnat_cuda/edit_dist.cu", + "fairseq/clib/libnat_cuda/binding.cpp", + ], + ), + cpp_extension.CppExtension( + "fairseq.ngram_repeat_block_cuda", + sources=[ + "fairseq/clib/cuda/ngram_repeat_block_cuda.cpp", + "fairseq/clib/cuda/ngram_repeat_block_cuda_kernel.cu", + ], + ), + cpp_extension.CppExtension( + "alignment_train_cuda_binding", + sources=[ + "examples/operators/alignment_train_kernel.cu", + "examples/operators/alignment_train_cuda.cpp", + ], + ), + ] + ) + cmdclass["build_ext"] = cpp_extension.BuildExtension + +except ImportError: + pass + + +if "READTHEDOCS" in os.environ: + # don't build extensions when generating docs + extensions = [] + if "build_ext" in cmdclass: + del cmdclass["build_ext"] + + # use CPU build of PyTorch + dependency_links = [ + "https://download.pytorch.org/whl/cpu/torch-1.7.0%2Bcpu-cp36-cp36m-linux_x86_64.whl" + ] +else: + dependency_links = [] + + +if "clean" in sys.argv[1:]: + # Source: https://bit.ly/2NLVsgE + print("deleting Cython files...") + + subprocess.run( + ["rm -f fairseq/*.so fairseq/**/*.so fairseq/*.pyd fairseq/**/*.pyd"], + shell=True, + ) + + +extra_packages = [] +if os.path.exists(os.path.join("fairseq", "model_parallel", "megatron", "mpu")): + extra_packages.append("fairseq.model_parallel.megatron.mpu") + + +def do_setup(package_data): + setup( + name="fairseq", + version=version, + description="Facebook AI Research Sequence-to-Sequence Toolkit", + url="https://github.com/pytorch/fairseq", + classifiers=[ + "Intended Audience :: Science/Research", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3.6", + "Programming Language :: Python :: 3.7", + "Programming Language :: Python :: 3.8", + "Topic :: Scientific/Engineering :: Artificial Intelligence", + ], + long_description=readme, + long_description_content_type="text/markdown", + setup_requires=[ + "cython", + 'numpy<1.20.0; python_version<"3.7"', + 'numpy; python_version>="3.7"', + "setuptools>=18.0", + ], + install_requires=[ + "cffi", + "cython", + 'dataclasses; python_version<"3.7"', + "hydra-core>=1.0.7,<1.1", + "omegaconf<2.1", + 'numpy<1.20.0; python_version<"3.7"', + 'numpy; python_version>="3.7"', + "regex", + "sacrebleu>=1.4.12", + #"torch", + "tqdm", + "bitarray", + #"torchaudio>=0.8.0", + ], + dependency_links=dependency_links, + packages=find_packages( + exclude=[ + "examples", + "examples.*", + "scripts", + "scripts.*", + "tests", + "tests.*", + ] + ) + + extra_packages, + package_data=package_data, + ext_modules=extensions, + test_suite="tests", + entry_points={ + "console_scripts": [ + "fairseq-eval-lm = fairseq_cli.eval_lm:cli_main", + "fairseq-generate = fairseq_cli.generate:cli_main", + "fairseq-hydra-train = fairseq_cli.hydra_train:cli_main", + "fairseq-interactive = fairseq_cli.interactive:cli_main", + "fairseq-preprocess = fairseq_cli.preprocess:cli_main", + "fairseq-score = fairseq_cli.score:cli_main", + "fairseq-train = fairseq_cli.train:cli_main", + "fairseq-validate = fairseq_cli.validate:cli_main", + ], + }, + cmdclass=cmdclass, + zip_safe=False, + ) + + +def get_files(path, relative_to="fairseq"): + all_files = [] + for root, _dirs, files in os.walk(path, followlinks=True): + root = os.path.relpath(root, relative_to) + for file in files: + if file.endswith(".pyc"): + continue + all_files.append(os.path.join(root, file)) + return all_files + + +if __name__ == "__main__": + try: + # symlink examples into fairseq package so package_data accepts them + fairseq_examples = os.path.join("fairseq", "examples") + if "build_ext" not in sys.argv[1:] and not os.path.exists(fairseq_examples): + os.symlink(os.path.join("..", "examples"), fairseq_examples) + + package_data = { + "fairseq": ( + get_files(fairseq_examples) + + get_files(os.path.join("fairseq", "config")) + ) + } + do_setup(package_data) + finally: + if "build_ext" not in sys.argv[1:] and os.path.islink(fairseq_examples): + os.unlink(fairseq_examples) diff --git a/PyTorch/NLP/new-Transformer/single.sh b/PyTorch/NLP/new-Transformer/single.sh new file mode 100644 index 00000000..af9c766f --- /dev/null +++ b/PyTorch/NLP/new-Transformer/single.sh @@ -0,0 +1,44 @@ +#!/bin/bash +export HSA_FORCE_FINE_GRAIN_PCIE=1 +export MIOPEN_FIND_MODE=1 +export MIOPEN_DEBUG_DISABLE_FIND_DB=1 +export NCCL_SOCKET_IFNAME=ib0 +export HSA_USERPTR_FOR_PAGED_MEM=0 +lrank=$OMPI_COMM_WORLD_LOCAL_RANK +comm_rank=$OMPI_COMM_WORLD_RANK +comm_size=$OMPI_COMM_WORLD_SIZE +TOKENS=2056 +DATA_PATH=~/data/wmt14_en_de_joined_dict +APP="python3 train.py $DATA_PATH --arch transformer_wmt_en_de --share-decoder-input-output-embed --optimizer adam --adam-betas '(0.9,0.98)' --clip-norm 0.0 --lr 5e-4 --lr-scheduler inverse_sqrt --warmup-updates 4000 --dropout 0.3 --weight-decay 0.0001 --criterion label_smoothed_cross_entropy --label-smoothing 0.1 --max-tokens $TOKENS --eval-bleu --eval-bleu-args {\"beam\":5,\"max_len_a\":1.2,\"max_len_b\":10} --eval-bleu-detok moses --eval-bleu-remove-bpe --eval-bleu-print-samples --best-checkpoint-metric bleu --maximize-best-checkpoint-metric --distributed-rank ${comm_rank} --distributed-world-size ${comm_size} --device-id ${lrank} --local_rank ${lrank} --distributed-init-method tcp://${1}:34567 --distributed-no-spawn --max-epoch 1" + +case ${lrank} in +[0]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_0:1 + export UCX_IB_PCI_BW=mlx5_0:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + ;; +[1]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_1:1 + export UCX_IB_PCI_BW=mlx5_1:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + ;; +[2]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_2:1 + export UCX_IB_PCI_BW=mlx5_2:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + ;; +[3]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_3:1 + export UCX_IB_PCI_BW=mlx5_3:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + ;; +esac + diff --git a/PyTorch/NLP/new-Transformer/single_fp16.sh b/PyTorch/NLP/new-Transformer/single_fp16.sh new file mode 100644 index 00000000..00bf0078 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/single_fp16.sh @@ -0,0 +1,43 @@ +#!/bin/bash +export MIOPEN_DEBUG_DISABLE_FIND_DB=1 +export NCCL_SOCKET_IFNAME=eno1 +export HSA_USERPTR_FOR_PAGED_MEM=0 +export HSA_FORCE_FINE_GRAIN_PCIE=1 +export MIOPEN_FIND_MODE=1 +lrank=$OMPI_COMM_WORLD_LOCAL_RANK +comm_rank=$OMPI_COMM_WORLD_RANK +comm_size=$OMPI_COMM_WORLD_SIZE +TOKENS=2560 +export DATA_PATH=~/data/wmt14_en_de_joined_dict +APP="python3 train.py $DATA_PATH --save-dir module4-fp16-2560 --arch transformer_wmt_en_de --share-decoder-input-output-embed --optimizer adam --adam-betas (0.9,0.98) --clip-norm 0.0 --lr 5e-4 --lr-scheduler inverse_sqrt --warmup-updates 4000 --dropout 0.3 --weight-decay 0.0001 --criterion label_smoothed_cross_entropy --label-smoothing 0.1 --max-tokens $TOKENS --eval-bleu --eval-bleu-args {\"beam\":5,\"max_len_a\":1.2,\"max_len_b\":10} --eval-bleu-detok moses --eval-bleu-remove-bpe --eval-bleu-print-samples --best-checkpoint-metric bleu --maximize-best-checkpoint-metric --distributed-rank ${comm_rank} --distributed-world-size ${comm_size} --device-id ${lrank} --local_rank ${lrank} --distributed-init-method tcp://${1}:34567 --distributed-no-spawn --max-epoch 1 --fp16" +case ${lrank} in +[0]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_0:1 + export UCX_IB_PCI_BW=mlx5_0:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + ;; +[1]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_1:1 + export UCX_IB_PCI_BW=mlx5_1:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + ;; +[2]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_2:1 + export UCX_IB_PCI_BW=mlx5_2:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + ;; +[3]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_3:1 + export UCX_IB_PCI_BW=mlx5_3:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + ;; +esac + diff --git a/PyTorch/NLP/new-Transformer/single_process.sh b/PyTorch/NLP/new-Transformer/single_process.sh new file mode 100644 index 00000000..23e9c7a3 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/single_process.sh @@ -0,0 +1,43 @@ +#!/bin/bash +export MIOPEN_DEBUG_DISABLE_FIND_DB=1 +export NCCL_SOCKET_IFNAME=eno1 +export HSA_USERPTR_FOR_PAGED_MEM=0 +export HSA_FORCE_FINE_GRAIN_PCIE=1 +export MIOPEN_FIND_MODE=1 +lrank=$OMPI_COMM_WORLD_LOCAL_RANK +comm_rank=$OMPI_COMM_WORLD_RANK +comm_size=$OMPI_COMM_WORLD_SIZE +TOKENS=4096 +export DATA_PATH=~/data/wmt14_en_de_joined_dict +APP="python3 train.py $DATA_PATH --save-dir module-4096 --arch transformer_wmt_en_de --share-decoder-input-output-embed --optimizer adam --adam-betas (0.9,0.98) --clip-norm 0.0 --lr 5e-4 --lr-scheduler inverse_sqrt --warmup-updates 4000 --dropout 0.3 --weight-decay 0.0001 --criterion label_smoothed_cross_entropy --label-smoothing 0.1 --max-tokens $TOKENS --eval-bleu --eval-bleu-args {\"beam\":5,\"max_len_a\":1.2,\"max_len_b\":10} --eval-bleu-detok moses --eval-bleu-remove-bpe --eval-bleu-print-samples --best-checkpoint-metric bleu --maximize-best-checkpoint-metric --distributed-rank ${comm_rank} --distributed-world-size ${comm_size} --device-id ${lrank} --local_rank ${lrank} --distributed-init-method tcp://${1}:34567 --distributed-no-spawn --max-epoch 1" +case ${lrank} in +[0]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_0:1 + export UCX_IB_PCI_BW=mlx5_0:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=0 --membind=0 ${APP} + ;; +[1]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_1:1 + export UCX_IB_PCI_BW=mlx5_1:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=1 --membind=1 ${APP} + ;; +[2]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_2:1 + export UCX_IB_PCI_BW=mlx5_2:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=2 --membind=2 ${APP} + ;; +[3]) + export HIP_VISIBLE_DEVICES=0,1,2,3 + export UCX_NET_DEVICES=mlx5_3:1 + export UCX_IB_PCI_BW=mlx5_3:50Gbs + echo NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + NCCL_SOCKET_IFNAME=ib0 numactl --cpunodebind=3 --membind=3 ${APP} + ;; +esac + diff --git a/PyTorch/NLP/new-Transformer/train.py b/PyTorch/NLP/new-Transformer/train.py new file mode 100644 index 00000000..321de3d9 --- /dev/null +++ b/PyTorch/NLP/new-Transformer/train.py @@ -0,0 +1,14 @@ +#!/usr/bin/env python3 -u +# Copyright (c) Facebook, Inc. and its affiliates. +# +# This source code is licensed under the MIT license found in the +# LICENSE file in the root directory of this source tree. +""" +Legacy entry point. Use fairseq_cli/train.py or fairseq-train instead. +""" + +from fairseq_cli.train import cli_main + + +if __name__ == "__main__": + cli_main() -- GitLab

G;o=@i=Z1O(oM{()(WV07m|8S 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
Dsm#==2=JVe9%Q^g}CeTlTP7LK6+ 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

+ +
+
+ Support Ukraine + MIT License + Latest Release + Build Status + Documentation Status +