Improve model card: Add detailed description, usage, links, and training info for LoRI-D adapter

README.md

@@ -2,192 +2,203 @@
 base_model: meta-llama/Meta-Llama-3-8B
 library_name: peft
 pipeline_tag: text-generation
+license: apache-2.0
+tags:
+  - lora
+  - peft
+  - multi-task-learning
+  - continual-learning
+  - nlu
+  - code-generation
+  - mathematical-reasoning
+  - safety-alignment
 ---
 
 # Model Card for LoRI-D_nlu_llama3_rank_32
 
 This model is part of [LoRI: Reducing Cross-Task Interference in Multi-Task Low-Rank Adaptation](https://arxiv.org/abs/2504.07448).
 
-<!-- Provide a quick summary of what the model is/does. -->
-
+**LoRI** (LoRA with Reduced Interference) is a simple yet effective parameter-efficient fine-tuning (PEFT) method designed for Large Language Models (LLMs) to mitigate notable overhead and address parameter interference in multi-task scenarios. It achieves this by freezing the projection matrices `A` as random projections and sparsifying the matrices `B` using task-specific masks. This design substantially reduces the number of trainable parameters while maintaining strong task performance. Moreover, LoRI minimizes cross-task interference in adapter merging by leveraging the orthogonality between adapter subspaces, and supports continual learning by using sparsity to mitigate catastrophic forgetting.
 
+<div align="center">
+    <img src="https://github.com/juzhengz/LoRI/raw/main/LoRI.png" alt="LoRI" width="80%">
+</div>
 
 ## Model Details
 
 ### Model Description
 
-<!-- Provide a longer summary of what this model is. -->
-
-
-
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+LoRI-D_nlu_llama3_rank_32 is a LoRI adapter specifically fine-tuned for Natural Language Understanding (NLU) tasks. It is based on the `meta-llama/Meta-Llama-3-8B` base model with a LoRA rank of 32. This model leverages LoRI's design to offer efficient fine-tuning, reduced parameter overhead, and minimized cross-task interference.
 
-### Model Sources [optional]
+- **Developed by:** [Juzheng Zhang](https://juzhengz.github.io/), [Jiacheng You](https://github.com/YouJiacheng), [Ashwinee Panda](https://kiddyboots216.github.io/), [Tom Goldstein](https://www.cs.umd.edu/~tomg/)
+- **Model type:** Low-Rank Adaptation (LoRA) variant / PEFT adapter
+- **Language(s) (NLP):** English
+- **License:** Apache 2.0
+- **Finetuned from model:** `meta-llama/Meta-Llama-3-8B`
 
-<!-- Provide the basic links for the model. -->
+### Model Sources
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+- **Repository:** [https://github.com/juzhengz/LoRI/](https://github.com/juzhengz/LoRI/)
+- **Paper:** [https://arxiv.org/abs/2504.07448](https://arxiv.org/abs/2504.07448)
+- **Project Page:** [https://juzhengz.github.io/](https://juzhengz.github.io/)
+- **Hugging Face Collection:** [https://huggingface.co/collections/tomg-group-umd/lori-adapters-67f795549d792613e1290011](https://huggingface.co/collections/tomg-group-umd/lori-adapters-67f795549d792613e1290011)
 
 ## Uses
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
-
 ### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+This model is intended for use in fine-tuning Large Language Models for various tasks, including:
+- Natural Language Understanding (NLU)
+- Mathematical reasoning
+- Code generation
+- Safety alignment
 
-[More Information Needed]
+It is particularly useful for researchers and practitioners looking for parameter-efficient fine-tuning solutions that reduce cross-task interference in multi-task and continual learning settings.
 
-### Downstream Use [optional]
+### Out-of-Scope Use
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+This model is not intended for:
+- Deployment in high-stakes applications requiring extremely high safety or ethical standards without further rigorous evaluation and fine-tuning.
+- Generating content that is harmful, discriminatory, or promotes illegal activities.
+- Use cases outside the specific tasks for which it has been fine-tuned without additional adaptation and validation.
+- Use without a compatible base model, as it is a PEFT adapter.
 
-[More Information Needed]
+## Bias, Risks, and Limitations
 
-### Out-of-Scope Use
+As an adapter fine-tuned on a base Large Language Model (e.g., Llama-3-8B), this model inherits potential biases present in its foundational training data. This could lead to biased, harmful, or undesirable outputs. While LoRI aims to reduce cross-task interference, complex interactions in highly diverse multi-task setups might still occur. Performance on out-of-distribution data or tasks not covered during its training may vary.
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+### Recommendations
 
-[More Information Needed]
+Users (both direct and downstream) should be made aware of the risks, biases, and limitations of the model. It is recommended to perform thorough evaluations specific to your application and data before deployment. Implement additional filtering or human-in-the-loop validation for critical use cases.
 
-## Bias, Risks, and Limitations
+## How to Get Started with the Model
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+Pretrained LoRI adapters are available on the Hugging Face Hub. To use this specific NLU adapter with its base model (`meta-llama/Meta-Llama-3-8B`), follow the example below:
 
-[More Information Needed]
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from peft import PeftModel
+import torch
 
-### Recommendations
+# Load the base model (Meta-Llama-3-8B)
+base_model_name = "meta-llama/Meta-Llama-3-8B"
+base_model = AutoModelForCausalLM.from_pretrained(
+    base_model_name,
+    torch_dtype=torch.bfloat16, # Use bfloat16 for Llama-3 if your hardware supports it
+    device_map="auto" # Automatically maps model to available devices (e.g., GPU)
+)
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+# Load the LoRI-D NLU adapter on top of the base model
+lori_adapter_name = "tomg-group-umd/LoRI-D_nlu_llama3_rank_32"
+model = PeftModel.from_pretrained(base_model, lori_adapter_name)
 
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
+# Load the tokenizer
+tokenizer = AutoTokenizer.from_pretrained(base_model_name)
 
-## How to Get Started with the Model
+# Example for text generation
+prompt = "The quick brown fox jumps over the lazy"
+inputs = tokenizer(prompt, return_tensors="pt").to(model.device) # Move inputs to model's device
 
-Use the code below to get started with the model.
+# Generate text
+model.eval() # Set model to evaluation mode
+with torch.no_grad():
+    outputs = model.generate(**inputs, max_new_tokens=50, temperature=0.7, do_sample=True)
+generated_text = tokenizer.decode(outputs[0], skip_special_tokens=True)
 
-[More Information Needed]
+print(f"Prompt: {prompt}")
+print(f"Generated: {generated_text}")
+```
 
 ## Training Details
 
 ### Training Data
 
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
+LoRI models are trained and evaluated on a variety of datasets covering different tasks:
+- **Natural Language Understanding (NLU):** Specific NLU datasets (details in the main repository and paper).
+- **Code Generation:** CodeAlpaca dataset.
+- **Mathematical Reasoning:** GSM8K dataset.
+- **Safety Alignment:** Saferpaca dataset.
 
-[More Information Needed]
+For more detailed information on specific datasets used for each task, please refer to the [LoRI GitHub repository](https://github.com/juzhengz/LoRI/) and the accompanying [paper](https://arxiv.org/abs/2504.07448).
 
 ### Training Procedure
 
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
+LoRI is implemented using Fully Sharded Data Parallel (FSDP) and can be executed in a multi-GPU environment. The training process typically involves two stages:
+1.  **LoRI-D Training:** Initial training of the LoRI adapter (Decomposed LoRA) to extract sparse masks.
+2.  **LoRI-S Training:** Continued training (Sparsified LoRA) at 90% sparsity, leveraging the extracted masks.
 
+The provided training scripts in the GitHub repository support LLaMA-3-8B and Mistral-7B base models with adapter ranks of 32 and 64, performing both `LoRI-D` and `LoRI-S` training, followed by evaluation on downstream tasks.
 
 #### Training Hyperparameters
 
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
+The specific LoRA parameters for this `LoRI-D_nlu_llama3_rank_32` adapter, as extracted from `adapter_config.json`, are:
+-   `r`: 32
+-   `lora_alpha`: 64
+-   `lora_dropout`: 0.05
+-   `target_modules`: `["down_proj", "up_proj", "k_proj", "gate_proj", "v_proj", "q_proj", "o_proj"]`
+-   `peft_type`: `LORA`
+-   **Training regime:** Mixed precision (commonly fp16 or bf16 for LLMs).
 
 ## Evaluation
 
-<!-- This section describes the evaluation protocols and provides the results. -->
-
 ### Testing Data, Factors & Metrics
 
-#### Testing Data
+The model's performance was evaluated extensively across various benchmarks relevant to Natural Language Understanding, Code Generation, Mathematical Reasoning, and Safety Alignment.
 
-<!-- This should link to a Dataset Card if possible. -->
+#### Testing Data
 
-[More Information Needed]
+Performance was evaluated on standard benchmarks for each task. Specific datasets include HumanEval for code generation, GSM8K for mathematical reasoning, and Saferpaca for safety alignment.
 
 #### Factors
 
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
+Evaluations disaggregated by tasks (NLU, code, math, safety) and potentially by model size/rank.
 
 #### Metrics
 
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
+Performance was measured using standard metrics relevant to each task (e.g., accuracy for NLU/math, pass@1 for code generation).
 
 ### Results
 
-[More Information Needed]
-
-#### Summary
-
-
+Extensive experiments demonstrated that LoRI consistently outperforms full fine-tuning and existing PEFT methods, while using up to 95% fewer trainable parameters than standard LoRA. In multi-task experiments, LoRI enabled effective adapter merging and continual learning with significantly reduced cross-task interference. For detailed evaluation results and comparisons, please refer to the [LoRI paper](https://arxiv.org/abs/2504.07448).
 
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Technical Specifications [optional]
+## Technical Specifications
 
 ### Model Architecture and Objective
 
-[More Information Needed]
+LoRI introduces modifications to the standard LoRA architecture. It freezes the low-rank projection matrix `A` as random projections and sparsifies the `B` matrix using task-specific masks. This approach aims to achieve mutual orthogonality between adapter subspaces, reduce cross-task interference, and significantly decrease the number of trainable parameters.
 
 ### Compute Infrastructure
 
-[More Information Needed]
-
 #### Hardware
 
-[More Information Needed]
+Training and evaluation were conducted on GPUs. Specific details on hardware configurations might be found within the supplementary materials of the paper or the GitHub repository's training scripts.
 
 #### Software
 
-[More Information Needed]
-
-## Citation [optional]
+The codebase primarily leverages PyTorch for deep learning, along with the `transformers` and `peft` libraries from Hugging Face.
 
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
+## Citation
 
-**BibTeX:**
+If you use LoRI in your work, please cite the following paper:
 
-[More Information Needed]
+```bibtex
+@article{zhang2025lori,
+  title={LoRI: Reducing Cross-Task Interference in Multi-Task Low-Rank Adaptation},
+  author={Zhang, Juzheng and You, Jiacheng and Panda, Ashwinee and Goldstein, Tom},
+  journal={arXiv preprint arXiv:2504.07448},
+  year={2025}
+}
+```
 
 **APA:**
-
 [More Information Needed]
 
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
+## Model Card Authors
+Niels, Hugging Face Community Science team.
 
 ## Model Card Contact
+For questions about the model or LoRI project, please contact [[email protected]](mailto:[email protected]).
 
-[More Information Needed]
 ### Framework versions
 
 - PEFT 0.12.0