# GraLoRA

[**Granular Low-Rank Adaptation (GraLoRA)**](https://huggingface.co/papers/2505.20355) là một phương pháp PEFT được thiết kế để tăng cường **khả năng biểu diễn** của low-rank adaptation đồng thời cải thiện **sự bền vững với các kích hoạt ngoại lai**, dựa trên những hiểu biết từ các vấn đề phổ biến trong lượng tử hóa.

![GraLoRA Overview](https://github.com/SqueezeBits/GraLoRA/raw/main/figure/gralora_overview.png)

Khác với LoRA tiêu chuẩn, vốn áp dụng một bộ thích ứng hạng thấp duy nhất trên toàn bộ không gian đặc trưng, GraLoRA giới thiệu một phương án thích ứng có cấu trúc và chi tiết hơn. Nó chia không gian thích ứng thành một lưới gồm $𝑘^2$ cặp bộ thích ứng nhỏ hơn, độc lập, mỗi cặp chịu trách nhiệm cho một tập con cục bộ của các chiều đầu vào và đầu ra. Do đó, mỗi bộ thích ứng hoạt động trên một không gian con có kích thước nhỏ hơn $k$ lần theo cả hai chiều so với bộ thích ứng LoRA gốc.

Việc phân rã chi tiết này cho phép các cập nhật được định vị theo không gian và nhận thức ngữ cảnh, từ đó tăng hiệu quả khả năng biểu diễn mà không cần thêm tham số hay chi phí tính toán. Bằng cách cô lập ảnh hưởng của các kích hoạt cực đoan trong các không gian con nhỏ hơn, GraLoRA giảm thiểu sự méo mó của gradient và duy trì sự cân bằng giữa các kênh trong quá trình thích ứng.

---

Tóm tắt từ bài báo là:

*Low-Rank Adaptation (LoRA) là một phương pháp phổ biến để tinh chỉnh hiệu quả tham số (PEFT) các mô hình sinh, được đánh giá cao nhờ sự đơn giản và hiệu quả. Mặc dù đã có những cải tiến gần đây, LoRA vẫn tồn tại một hạn chế cơ bản: quá khớp (overfitting) khi mở rộng nút cổ chai (bottleneck). Phương pháp này đạt hiệu suất tốt nhất ở bậc (rank) 32–64, nhưng độ chính xác lại chững lại hoặc giảm ở các bậc cao hơn, vẫn chưa đạt được hiệu suất của tinh chỉnh đầy đủ (FFT). Chúng tôi xác định nguyên nhân gốc rễ là nút cổ chai cấu trúc của LoRA, gây ra sự vướng víu gradient (gradient entanglement) giữa các kênh đầu vào không liên quan và làm méo mó quá trình lan truyền gradient. Để giải quyết vấn đề này, chúng tôi đề xuất một cấu trúc mới, Granular Low-Rank Adaptation (GraLoRA), chia các ma trận trọng số thành các khối con (sub-blocks), mỗi khối có bộ thích ứng bậc thấp (low-rank adapter) riêng. Với chi phí tính toán hoặc lưu trữ không đáng kể, GraLoRA khắc phục các hạn chế của LoRA, tăng hiệu quả khả năng biểu diễn và xấp xỉ hành vi của FFT sát hơn. Các thí nghiệm trên các bộ chuẩn (benchmarks) về tạo mã, suy luận thông thường, suy luận toán học, hiểu ngôn ngữ chung và tạo ảnh cho thấy GraLoRA luôn vượt trội hơn LoRA và các phương pháp cơ sở khác, đạt mức tăng tuyệt đối lên đến +8,5% về Pass@1 trên HumanEval+. Những cải thiện này được duy trì qua các kích thước mô hình và cài đặt bậc khác nhau, khiến GraLoRA trở thành một giải pháp có khả năng mở rộng và bền vững cho PEFT.*

## Tổng quan về benchmark

<iframe src="https://peft-internal-testing-peft-method-comparison-embed.hf.space/?highlight[type]=GRALORA" frameborder="0" width="850" height="1000"
>

# API

## GraloraConfig[[peft.GraloraConfig]]

#### peft.GraloraConfig[[peft.GraloraConfig]]

```python
peft.GraloraConfig(task_type: Optional[Union[str, TaskType]] = None, peft_type: Optional[Union[str, PeftType]] = None, auto_mapping: Optional[dict] = None, peft_version: Optional[str] = None, base_model_name_or_path: Optional[str] = None, revision: Optional[str] = None, inference_mode: bool = False, r: int = 32, hybrid_r: int = 0, target_modules: list[str] | str | None = None, alpha: int = 64, gralora_dropout: float = 0.0, gralora_k: int = 2, fan_in_fan_out: bool = False, bias: str = 'none', modules_to_save: list[str] | None = None, init_weights: bool = True, layers_to_transform: list[int] | int | None = None, layers_pattern: str | None = None)
```

[Nguồn](https://github.com/huggingface/peft/blob/main/src/peft/tuners/gralora/config.py#L23)

**Tham số:**

r (`int`) : Kích thước attention của GraLoRA xác định rank của adapter GraLoRA. Tổng số tham số của adapter GraLoRA giống với LoRA có cùng rank r, trong khi khả năng biểu diễn được nhân lên gralora_k lần.

hybrid_r (`int`) : Hybrid GraLoRA rank xác định rank được phân bổ cho phương pháp LoRA thông thường khi sử dụng phương pháp Hybrid GraLoRA. Hybrid GraLoRA, sự kết hợp giữa GraLoRA và LoRA thông thường, sẽ khả dụng khi hybrid_r > 0. Số lượng tham số của adapter GraLoRA là r + hybrid_r.

target_modules (`Union[List[str], str]`) : Danh sách tên module hoặc biểu thức regex của các tên module cần thay thế bằng GraLoRA. Ví dụ: ['q', 'v'] hoặc '.*decoder.*(SelfAttention|EncDecAttention).*(q|v)$'. Giá trị này cũng có thể là ký tự đại diện 'all-linear', khớp với tất cả các lớp linear/Conv1D (nếu model là PreTrainedModel, lớp output sẽ bị loại trừ). Nếu không được chỉ định, các module sẽ được chọn theo kiến trúc của model. Nếu kiến trúc không được biết đến, một lỗi sẽ được ném ra -- trong trường hợp này, bạn nên chỉ định các module đích thủ công.

alpha (`int`) : alpha của GraLoRA. Alpha của GraLoRA là hệ số tỷ lệ cho adapter GraLoRA. Hệ số tỷ lệ sẽ là alpha / (r + hybrid_r).

gralora_dropout (`float`) : GraLoRA dropout là xác suất dropout cho adapter GraLoRA. Nó được sử dụng để ngăn chặn overfitting và cải thiện khả năng tổng quát hóa của adapter GraLoRA.

gralora_k (`int`) : GraLoRA k xác định số lượng subblock trong adapter GraLoRA. Rank r phải chia hết cho gralora_k để adapter GraLoRA hợp lệ. Tổng số tham số được giữ nguyên bất kể giá trị của gralora_k. Rank tổng của adapter GraLoRA tăng lên gralora_k, trong khi rank của mỗi subblock giảm đi gralora_k. Khuyến nghị sử dụng gralora_k=2 cho rank 32 trở xuống và gralora_k=4 cho rank 64 trở lên.

fan_in_fan_out (`bool`) : Đặt giá trị này thành True nếu lớp cần thay thế lưu trọng số theo dạng (fan_in, fan_out). Ví dụ, gpt-2 sử dụng `Conv1D`, lưu trọng số theo dạng (fan_in, fan_out), do đó cần đặt giá trị này thành `True`.

bias (`str`) : Kiểu bias cho gralora. Có thể là 'none', 'all' hoặc 'gralora_only'. Nếu là 'all' hoặc 'gralora_only', các bias tương ứng sẽ được cập nhật trong quá trình huấn luyện. Lưu ý rằng điều này có nghĩa là, ngay cả khi vô hiệu hóa các adapter, mô hình sẽ không tạo ra cùng đầu ra như mô hình gốc nếu không có thích ứng.

modules_to_save (`Optional[list[str]]`) : Danh sách các module ngoài các lớp gralora cần được đặt là có thể huấn luyện và lưu trong checkpoint cuối cùng. Ví dụ, trong các tác vụ Phân loại Chuỗi hoặc Phân loại Token, lớp cuối cùng `classifier/score` được khởi tạo ngẫu nhiên và do đó cần phải có thể huấn luyện và được lưu lại.

init_weights (`bool`) : Có nên khởi tạo trọng số của các lớp GraLoRA với giá trị khởi tạo mặc định hay không. Không thay đổi cài đặt này, trừ khi bạn biết chính xác mình đang làm gì.

layers_to_transform (`Union[List[int], int]`) : Các chỉ số lớp cần biến đổi. Nếu tham số này được chỉ định, PEFT sẽ chỉ biến đổi các lớp có chỉ số nằm trong danh sách này. Nếu một số nguyên duy nhất được truyền vào, PEFT sẽ chỉ biến đổi lớp tại chỉ số đó. Điều này chỉ hoạt động khi target_modules là một danh sách các chuỗi str.

layers_pattern (`Optional[Union[List[str], str]]`) : Tên mẫu lớp, chỉ được sử dụng nếu `layers_to_transform` khác None và nếu mẫu lớp không nằm trong các mẫu lớp phổ biến. Điều này chỉ hoạt động khi target_modules là một danh sách str. Tham số này nên nhắm đến `nn.ModuleList` của mô hình, thường được gọi là `'layers'` hoặc `'h'`.

Đây là lớp cấu hình để lưu trữ cấu hình của một [GraloraModel](/docs/peft/main/vi/package_reference/gralora#peft.GraloraModel).

## GraloraModel[[peft.GraloraModel]]

#### peft.GraloraModel[[peft.GraloraModel]]

```python
peft.GraloraModel(model, peft_config: Union[PeftConfig, dict[str, PeftConfig]], adapter_name: str, low_cpu_mem_usage: bool = False, state_dict: Optional[dict[str, torch.Tensor]] = None)
```

[Nguồn](https://github.com/huggingface/peft/blob/main/src/peft/tuners/gralora/model.py#L28)

**Tham số:**

model ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)): Mô hình cần được thích ứng.

config ([GraloraConfig](/docs/peft/main/vi/package_reference/gralora#peft.GraloraConfig)) : Cấu hình của mô hình Gralora.

adapter_name (`str`) : Tên của adapter, mặc định là `"default"`.

**Trả về:** `torch.nn.Module`

Mô hình Gralora.

Tạo mô hình Random Matrix Adaptation dựa trên Vector (Gralora) từ một mô hình transformers được huấn luyện trước.

Ví dụ:

```py
>>> from transformers import AutoModelForCausalLM
>>> from peft import GraloraConfig, get_peft_model

>>> base_model = AutoModelForCausalLM.from_pretrained("facebook/opt-125m")
>>> config = GraloraConfig(r=128)
>>> model = get_peft_model(base_model, config)
```

**Thuộc tính**:
- **model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- Mô hình cần được thích ứng.
- **peft_config** ([GraloraConfig](/docs/peft/main/vi/package_reference/gralora#peft.GraloraConfig)): Cấu hình của mô hình Gralora.