From 13476a807ccd86189809dd00e627da93dfab5aff Mon Sep 17 00:00:00 2001 From: Sourab Mangrulkar <13534540+pacman100@users.noreply.github.com> Date: Mon, 27 Mar 2023 13:44:00 +0530 Subject: [PATCH] Apply suggestions from code review Co-authored-by: Steven Liu <59462357+stevhliu@users.noreply.github.com> --- .github/workflows/build_documentation.yml | 2 +- Makefile | 4 +-- docs/README.md | 8 ++--- docs/_toctree.yml | 2 +- docs/index.mdx | 15 +++------ docs/install.mdx | 15 ++++----- docs/quicktour.mdx | 41 +++++++++++------------ 7 files changed, 39 insertions(+), 48 deletions(-) diff --git a/.github/workflows/build_documentation.yml b/.github/workflows/build_documentation.yml index 082ece2..309d35a 100644 --- a/.github/workflows/build_documentation.yml +++ b/.github/workflows/build_documentation.yml @@ -12,6 +12,6 @@ jobs: uses: huggingface/doc-builder/.github/workflows/build_main_documentation.yml@main with: commit_sha: ${{ github.sha }} - package: accelerate + package: peft secrets: token: ${{ secrets.HUGGINGFACE_PUSH }} diff --git a/Makefile b/Makefile index 3b6db1f..145a375 100644 --- a/Makefile +++ b/Makefile @@ -8,13 +8,13 @@ check_dirs := src tests examples docs quality: black --check $(check_dirs) ruff $(check_dirs) - doc-builder style src tests docs --max_len 119 --check_only + doc-builder style src/peft tests docs/source --max_len 119 --check_only # Format source code automatically and check is there are any problems left that need manual fixing style: black $(check_dirs) ruff $(check_dirs) --fix - doc-builder style src tests docs --max_len 119 + doc-builder style src/peft tests docs/source --max_len 119 test: pytest tests/ \ No newline at end of file diff --git a/docs/README.md b/docs/README.md index 32e51f1..5955736 100644 --- a/docs/README.md +++ b/docs/README.md @@ -43,7 +43,7 @@ Once you have setup the `doc-builder` and additional packages, you can generate typing the following command: ```bash -doc-builder build accelerate docs/source/ --build_dir ~/tmp/test-build +doc-builder build peft docs/source/ --build_dir ~/tmp/test-build ``` You can adapt the `--build_dir` to set any temporary folder that you prefer. This command will create it and generate @@ -67,7 +67,7 @@ doc-builder preview {package_name} {path_to_docs} For example: ```bash -doc-builder preview transformers docs/source/en/ +doc-builder preview peft docs/source ``` The docs will be viewable at [http://localhost:3000](http://localhost:3000). You can also preview the docs once you have opened a PR. You will see a bot add a comment to a link where the documentation with your changes lives. @@ -84,7 +84,7 @@ The `preview` command only works with existing doc files. When you add a complet Accepted files are Markdown (.md or .mdx). Create a file with its extension and put it in the source directory. You can then link it to the toc-tree by putting -the filename without the extension in the [`_toctree.yml`](https://github.com/huggingface/accelerate/blob/main/docs/source/_toctree.yml) file. +the filename without the extension in the [`_toctree.yml`](https://github.com/huggingface/peft/blob/main/docs/source/_toctree.yml) file. ## Renaming section headers and moving sections @@ -112,7 +112,7 @@ Use the relative style to link to the new file so that the versioned docs contin ## Writing Documentation - Specification -The `huggingface/accelerate` documentation follows the +The `huggingface/peft` documentation follows the [Google documentation](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) style for docstrings, although we can write them directly in Markdown. diff --git a/docs/_toctree.yml b/docs/_toctree.yml index 4d6dd8b..211b83f 100644 --- a/docs/_toctree.yml +++ b/docs/_toctree.yml @@ -1,7 +1,7 @@ - title: Get Started sections: - local: index - title: 🤗 PEFT + title: 🤗 PEFT - local: quicktour title: Quicktour - local: installation diff --git a/docs/index.mdx b/docs/index.mdx index 9e1b4bd..4f5776f 100644 --- a/docs/index.mdx +++ b/docs/index.mdx @@ -12,18 +12,13 @@ specific language governing permissions and limitations under the License. # PEFT -🤗 PEFT is a library that enables using State-of-the-art Parameter-Efficient Fine-Tuning (PEFT) methods. +🤗 PEFT, or Parameter-Efficient Fine-Tuning (PEFT), is a library for efficiently adapting pre-trained language models (PLMs) to various downstream applications without fine-tuning all the model's parameters. +PEFT methods only fine-tune a small number of (extra) model parameters, significantly decreasing computational and storage costs because fine-tuning large-scale PLMs is prohibitively costly. +Recent state-of-the-art PEFT techniques achieve performance comparable to that of full fine-tuning. -PEFT methods enable efficient adaptation of pre-trained language models (PLMs) to -various downstream applications without fine-tuning all the model's parameters. -Fine-tuning large-scale PLMs is often prohibitively costly. -In this regard, PEFT methods only fine-tune a small number of (extra) model parameters, -thereby greatly decreasing the computational and storage costs. -Recent State-of-the-Art PEFT techniques achieve performance comparable to that of full fine-tuning. +PEFT is seamlessly integrated with 🤗 Accelerate for large-scale models leveraging DeepSpeed and [Big Model Inference](https://huggingface.co/docs/accelerate/usage_guides/big_modeling). -Seamlessly integrated with 🤗 Accelerate for large scale models leveraging DeepSpeed and Big Model Inference. - -Supported methods, with more coming soon: +Supported methods include: 1. LoRA: [LORA: LOW-RANK ADAPTATION OF LARGE LANGUAGE MODELS](https://arxiv.org/pdf/2106.09685.pdf) 2. Prefix Tuning: [Prefix-Tuning: Optimizing Continuous Prompts for Generation](https://aclanthology.org/2021.acl-long.353/), [P-Tuning v2: Prompt Tuning Can Be Comparable to Fine-tuning Universally Across Scales and Tasks](https://arxiv.org/pdf/2110.07602.pdf) diff --git a/docs/install.mdx b/docs/install.mdx index e086ed8..5f5ecff 100644 --- a/docs/install.mdx +++ b/docs/install.mdx @@ -10,26 +10,23 @@ an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express o specific language governing permissions and limitations under the License. --> -# Installation and Configuration +# Installation Before you start, you will need to setup your environment, install the appropriate packages, and configure 🤗 PEFT. 🤗 PEFT is tested on **Python 3.7+**. -## Installing 🤗 PEFT +🤗 PEFT is available on pypi, as well as GitHub: -🤗 PEFT is available on pypi, as well as on GitHub. Details to install from each are below: +## pip -### pip - -To install 🤗 PEFT from pypi, perform: +To install 🤗 PEFT from pypi: ```bash pip install peft ``` -### Source +## Source -New features are added every day that haven't been released yet. To try them out yourself, install -from the GitHub repository: +New features that haven't been released yet are added every day, which also means there may be some bugs. To try them out, install from the GitHub repository: ```bash pip install git+https://github.com/huggingface/peft diff --git a/docs/quicktour.mdx b/docs/quicktour.mdx index 45ee22c..e0eb37f 100644 --- a/docs/quicktour.mdx +++ b/docs/quicktour.mdx @@ -12,15 +12,16 @@ specific language governing permissions and limitations under the License. # Quick tour -Let's have a look at the 🤗 PEFT main features and traps to avoid. +Let's have a look at 🤗 PEFT's main features and learn how to set up a `PeftModel` and train it with 🤗 Accelerate's DeepSpeed integration and use it for inference. ## Main use -To use 🤗 PEFT in your script, you have to follow below steps: +To use 🤗 PEFT in your script: -1. Create a `PeftConfig` object corresponding to your PEFT method. -Please refer to the [Config Page](package_reference/config) for more details. -Below, we will use `LoRAConfig` for demonstration. +1. Each PEFT method is defined by a `PeftConfig` object. + +Create a `PeftConfig` object corresponding to your PEFT method (see the [Configuration](package_reference/config) reference for more details) and [`TaskType`], the type of task you're training your model for. +This example trains the [`bigscience/mt0-large`](https://huggingface.co/bigscience/mt0-large) model with the Low-Rank Adaptation of Large Language Models (LoRA) method. Load the `LoRAConfig`, and specify the `task_type` for sequence-to-sequence language modeling. ```python from peft import LoraConfig, TaskType @@ -41,7 +42,7 @@ tokenizer_name_or_path = "bigscience/mt0-large" model = AutoModelForSeq2SeqLM.from_pretrained(model_name_or_path) ``` -3. Preprocess your model if you use `bitsandbytes` for INT-8 quantized training; else skip this step. +3. Preprocess your model if you use [`bitsandbytes`](https://github.com/TimDettmers/bitsandbytes) for `int8` quantized training; otherwise, skip this step. ```python from peft import prepare_model_for_int8_training @@ -59,8 +60,7 @@ model.print_trainable_parameters() # output: trainable params: 2359296 || all params: 1231940608 || trainable%: 0.19151053100118282 ``` -5. Voila 🎉. Now, train the model using 🤗 Transformers Trainer API, 🤗 Accelerate or any custom PyTroch training loop. -Please refer example [peft_lora_seq2seq.ipynb](https://github.com/huggingface/peft/blob/main/examples/conditional_generation/peft_lora_seq2seq.ipynb) for an end-to-end example. +5. Voila 🎉! Now, train the model using the 🤗 Transformers Trainer API, 🤗 Accelerate, or any custom PyTroch training loop (take a look at the end-to-end [example](https://github.com/huggingface/peft/blob/main/examples/conditional_generation/peft_lora_seq2seq.ipynb) of training [`bigscience/mt0-large`](https://huggingface.co/bigscience/mt0-large)). ### Saving/loading a model @@ -71,10 +71,9 @@ model.save_pretrained("output_dir") # model.push_to_hub("my_awesome_peft_model") also works ``` -This will only save the incremental PEFT weights that were trained. -For example, you can find the `bigscience/T0_3B` tuned using LoRA on the `twitter_complaints` raft dataset here: -[smangrul/twitter_complaints_bigscience_T0_3B_LORA_SEQ_2_SEQ_LM](https://huggingface.co/smangrul/twitter_complaints_bigscience_T0_3B_LORA_SEQ_2_SEQ_LM). -Notice that it only contains 2 files: `adapter_config.json` and `adapter_model.bin` with the latter being just 19MB. +This only saves the incremental PEFT weights that were trained. +For example, [smangrul/twitter_complaints_bigscience_T0_3B_LORA_SEQ_2_SEQ_LM](https://huggingface.co/smangrul/twitter_complaints_bigscience_T0_3B_LORA_SEQ_2_SEQ_LM) is a `bigscience/T0_3B`model finetuned with LoRA on the [`twitter_complaints`](https://huggingface.co/datasets/ought/raft/viewer/twitter_complaints/train) RAFT dataset. +Notice that it only contains 2 files: `adapter_config.json` and `adapter_model.bin`, with the latter being just 19MB. 2. Load your model using the `from_pretrained` function. @@ -101,14 +100,14 @@ Notice that it only contains 2 files: `adapter_config.json` and `adapter_model.b ## Launching your distributed script PEFT models work with 🤗 Accelerate out of the box. -Use 🤗 Accelerate for Distributed training on various hardware such as GPUs, Apple Silicon devices etc during training. -Use 🤗 Accelerate for inferencing on consumer hardware with small resources. +You can use 🤗 Accelerate for distributed training on various hardware such as GPUs, or Apple Silicon devices during training, and for inference on consumer hardware with fewer resources. -### Example of PEFT model training using 🤗 Accelerate's DeepSpeed integration +### Train with 🤗 Accelerate's DeepSpeed integration -DeepSpeed version required `v0.8.0`. An example is provided in `~examples/conditional_generation/peft_lora_seq2seq_accelerate_ds_zero3_offload.py`. - a. First, run `accelerate config --config_file ds_zero3_cpu.yaml` and answer the questionnaire. - Below are the contents of the config file. +You'll need DeepSpeed version `v0.8.0` for this example. Feel free to check out the full example [script](https://github.com/huggingface/peft/blob/main/examples/conditional_generation/peft_lora_seq2seq_accelerate_ds_zero3_offload.py) for more details! + +1. Run `accelerate config --config_file ds_zero3_cpu.yaml` and answer the questionnaire to setup your environment. +Below are the contents of the config file. ```yaml compute_environment: LOCAL_MACHINE deepspeed_config: @@ -133,12 +132,12 @@ DeepSpeed version required `v0.8.0`. An example is provided in `~examples/condit same_network: true use_cpu: false ``` - b. run the below command to launch the example script +2. Run the following command to launch the example script: ```bash accelerate launch --config_file ds_zero3_cpu.yaml examples/peft_lora_seq2seq_accelerate_ds_zero3_offload.py ``` - c. output logs: +You'll see some output logs that look like this: ```bash GPU Memory before entering the train : 1916 GPU Memory consumed at the end of the train (end-begin): 66 @@ -163,7 +162,7 @@ DeepSpeed version required `v0.8.0`. An example is provided in `~examples/condit dataset['train'][label_column][:10]=['no complaint', 'no complaint', 'complaint', 'complaint', 'no complaint', 'no complaint', 'no complaint', 'complaint', 'complaint', 'no complaint'] ``` -### Example of PEFT model inference using 🤗 Accelerate's Big Model Inferencing capabilities +### Inference with 🤗 Accelerate's Big Model Inference An example is provided in `~examples/causal_language_modeling/peft_lora_clm_accelerate_big_model_inference.ipynb`. ## Model Support matrix