PEFT documentation
HiRA
HiRA
High-Rank Adaptation (HiRA) là một phương pháp PEFT mở rộng cách tiếp cận LoRA bằng cách áp dụng điều biến theo từng phần tử lên ma trận trọng số gốc. Thay vì thêm trực tiếp một bản cập nhật hạng thấp, HiRA tính toán:
trong đó là trọng số cơ sở, và là các nhân tử hạng thấp với hạng $r \ll \min(\text{in_features}, \text{out_features})$. Cách biểu diễn này cho phép HiRA điều chỉnh các trọng số hiện có bằng một sự điều biến nhân, phụ thuộc vào đầu vào, thường cải thiện hiệu quả fine-tuning trên các tác vụ downstream.
Tóm tắt từ bài báo HiRA là:
Chúng tôi đề xuất Hadamard High-Rank Adaptation (HiRA), một phương pháp tinh chỉnh hiệu quả tham số (PEFT) nhằm nâng cao khả năng thích ứng của các Mô hình Ngôn ngữ Lớn (LLM). Trong khi Low-rank Adaptation (LoRA) được sử dụng rộng rãi để giảm yêu cầu về tài nguyên, các bản cập nhật hạng thấp của nó có thể hạn chế khả năng biểu đạt cho các tác vụ mới. HiRA giải quyết vấn đề này bằng cách sử dụng tích Hadamard để giữ lại các tham số cập nhật hạng cao, từ đó cải thiện sức chứa của mô hình. Về mặt thực nghiệm, HiRA vượt trội hơn LoRA và các biến thể của nó trên một số tác vụ, với các nghiên cứu ablation toàn diện xác nhận hiệu quả của phương pháp này.
Ví dụ
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import get_peft_model
from peft.tuners.hira import HiraConfig
# Example 1: HiRA on opt-125m for causal language modeling
model_id = "facebook/opt-125m"
base_model = AutoModelForCausalLM.from_pretrained(model_id)
tokenizer = AutoTokenizer.from_pretrained(model_id)
# Define HiRA configuration: apply to the MLP dense layers in each transformer block
hira_config = HiraConfig(
r=32,
target_modules=["k_proj", "q_proj", "v_proj", "fc1", "fc2"],
hira_dropout=0.0,
init_weights=True,
)
peft_model = get_peft_model(base_model, hira_config)
peft_model.print_healthcheck()Tổng quan về benchmark
Trích dẫn:
Nếu bạn thấy HiRA hữu ích, vui lòng trích dẫn HiRA như sau:
@inproceedings{
huang2025hira,
title={Hi{RA}: Parameter-Efficient Hadamard High-Rank Adaptation for Large Language Models},
author={Qiushi Huang and Tom Ko and Zhan Zhuang and Lilian Tang and Yu Zhang},
booktitle={The Thirteenth International Conference on Learning Representations},
year={2025},
url={https://openreview.net/forum?id=TwJrTz9cRS}
}API
HiraConfig
lớp peft.HiraConfig
< source >( task_type: Optional[Union[str, TaskType]] = Nonepeft_type: Optional[Union[str, PeftType]] = Noneauto_mapping: Optional[dict] = Nonepeft_version: Optional[str] = Nonebase_model_name_or_path: Optional[str] = Nonerevision: Optional[str] = Noneinference_mode: bool = Falser: int = 32target_modules: Optional[Union[list[str], str]] = Noneexclude_modules: Optional[Union[list[str], str]] = Nonehira_dropout: float = 0.0fan_in_fan_out: bool = Falsemodules_to_save: Optional[list[str]] = Noneinit_weights: bool | Literal['gaussian'] | None = Truelayers_to_transform: Optional[Union[list[int], int]] = Nonelayers_pattern: Optional[Union[list[str], str]] = Nonerank_pattern: Optional[dict] = <factory> )
Tham số
- r (
int) — Rank của thành phần low-rank trong HiRA. Mặc dù HiRA đạt được sự thích ứng high-rank thông qua Hadamard fusion, giá trị này xác định chiều của phép phân tích low-rank cơ bản (các ma trận A và B). - target_modules (
Optional[Union[List[str], str]]) — Tên của các module cần áp dụng adapter. Nếu được chỉ định, chỉ các module có tên được chỉ định sẽ được thay thế. Khi truyền một chuỗi, một phép khớp regex sẽ được thực hiện. Khi truyền một danh sách các chuỗi, một phép khớp chính xác sẽ được thực hiện hoặc kiểm tra xem tên của module có kết thúc bằng bất kỳ chuỗi nào được truyền hay không. Nếu được chỉ định là ‘all-linear’, thì tất cả các module linear/Conv1D sẽ được chọn (nếu model là một 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 một cách thủ công. - exclude_modules (
Optional[Union[List[str], str]]) — Tên của các module không áp dụng adapter. Khi truyền một chuỗi, một phép khớp regex sẽ được thực hiện. Khi truyền một danh sách các chuỗi, một phép khớp chính xác sẽ được thực hiện hoặc kiểm tra xem tên của module có kết thúc bằng bất kỳ chuỗi nào được truyền vào hay không. - hira_dropout (
float) — Xác suất dropout cho các lớp HiRA. - 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ụngConv1Dlưu trọng số theo dạng (fan_in, fan_out) do đó giá trị này nên được đặt thànhTrue. - modules_to_save (
List[str]) — Danh sách các module ngoài các lớp adapter cần được đặt là có thể huấn luyện và lưu trong checkpoint cuối cùng. - init_weights (
bool|Literal["gaussian"]) — Cách khởi tạo trọng số của các lớp HiRA. Truyền True (mặc định) sẽ thực hiện khởi tạo mặc định, trong đó trọng số B của HiRA được đặt bằng 0. Điều này có nghĩa là nếu không huấn luyện thêm, bộ thích ứng HiRA sẽ không có tác dụng (no-op). Đặt khởi tạo thành False sẽ dẫn đến việc khởi tạo ngẫu nhiên cho HiRA A và B, tức là HiRA không phải là no-op trước khi huấn luyện; cài đặt này được dành cho mục đích gỡ lỗi. Truyền'gaussian'sẽ thực hiện khởi tạo Gaussian được chuẩn hóa theo rank của HiRA cho các lớp linear và layers. - layers_to_transform (
Union[List[int], int]) — Các chỉ số lớp cần biến đổi. Nếu truyền vào một danh sách các số nguyên, adapter sẽ được áp dụng cho các chỉ số lớp được chỉ định trong danh sách này. Nếu truyền vào một số nguyên duy nhất, các phép biến đổi sẽ được áp dụng cho lớp tại chỉ số này. - layers_pattern (
Optional[Union[List[str], str]]) — Tên mẫu lớp, chỉ được sử dụng nếulayers_to_transformkhácNone. Giá trị này cần nhắm đếnnn.ModuleListcủa mô hình, thường được gọi là'layers'hoặc'h'. - rank_pattern (
dict) — Bản ánh xạ từ tên lớp hoặc biểu thức chính quy đến các rank khác với r mặc định được chỉ định bởir. Ví dụ,{'^model.decoder.layers.0.encoder_attn.k_proj': 16}.
Đây là lớp cấu hình để lưu trữ cấu hình của HiraModel.
HiraModel
lớp peft.HiraModel
< source >( modelpeft_config: Union[PeftConfig, dict[str, PeftConfig]]adapter_name: strlow_cpu_mem_usage: bool = Falsestate_dict: Optional[dict[str, torch.Tensor]] = None ) → torch.nn.Module
Tham số
- model (
torch.nn.Module) — Mô hình cần được thích ứng. - config (HiraConfig) — Cấu hình của mô hình HiRA.
- adapter_name (
str) — Tên của adapter, mặc định là"default". - low_cpu_mem_usage (
bool,optional, mặc định làFalse) — Tạo trọng số adapter rỗng trên thiết bị meta. Hữu ích để tăng tốc quá trình tải.
Trả về
torch.nn.Module
Mô hình HiRA.
Tạo mô hình HiRA Adapter từ một mô hình transformers được huấn luyện trước.
Phương pháp này được mô tả chi tiết tại https://openreview.net/pdf?id=TwJrTz9cRS.
Ví dụ:
>>> from transformers import AutoModelForSeq2SeqLM
>>> from peft import HiraConfig, get_peft_model
>>> config = HiraConfig(
... task_type="SEQ_2_SEQ_LM",
... r=32,
... target_modules=["q", "v"],
... hira_dropout=0.01,
... )
>>> model = AutoModelForSeq2SeqLM.from_pretrained("t5-base")
>>> hira_model = get_peft_model(model, config)>>> import torch
>>> import transformers
>>> from peft import HiraConfig, get_peft_model, prepare_model_for_kbit_training
>>> rank = ...
>>> target_modules = ["q_proj", "k_proj", "v_proj", "out_proj", "fc_in", "fc_out", "wte"]
>>> config = HiraConfig(r=32, target_modules=target_modules, hira_dropout=0.1, task_type="CAUSAL_LM")
>>> quantization_config = transformers.BitsAndBytesConfig(load_in_8bit=True)
>>> tokenizer = transformers.AutoTokenizer.from_pretrained(
... "kakaobrain/kogpt",
... revision="KoGPT6B-ryan1.5b-float16", # or float32 version: revision=KoGPT6B-ryan1.5b
... bos_token="[BOS]",
... eos_token="[EOS]",
... unk_token="[UNK]",
... pad_token="[PAD]",
... mask_token="[MASK]",
... )
>>> model = transformers.GPTJForCausalLM.from_pretrained(
... "kakaobrain/kogpt",
... revision="KoGPT6B-ryan1.5b-float16", # or float32 version: revision=KoGPT6B-ryan1.5b
... pad_token_id=tokenizer.eos_token_id,
... use_cache=False,
... device_map={"": rank},
... torch_dtype=torch.float16,
... quantization_config=quantization_config,
... )
>>> model = prepare_model_for_kbit_training(model)
>>> hira_model = get_peft_model(model, config)Thuộc tính:
- model (PreTrainedModel) — Mô hình cần được thích ứng.
- peft_config (HiraConfig): Cấu hình của mô hình HiRA.
Các lớp cốt lõi
HiraLayer
lớp peft.tuners.hira.HiraLayer
< source >( base_layer: nn.Moduleephemeral_gpu_offload: bool = False**kwargs )
Linear Adapter
lớp peft.tuners.hira.Linear
< source >( base_layeradapter_name: strconfig: HiraConfigr: int = 0fan_in_fan_out: bool = Falseis_target_conv_1d_layer: bool = False**kwargs )
get_delta_weight
< source >( adapter )
Tính toán trọng số delta cho adapter đã cho.
merge
< source >( safe_merge: bool = Falseadapter_names: Optional[list[str]] = None )
Tham số
- safe_merge (
bool, tùy chọn) — Nếu là True, thao tác gộp sẽ được thực hiện trên một bản sao của trọng số gốc và kiểm tra các giá trị NaN trước khi gộp trọng số. Điều này hữu ích nếu bạn muốn kiểm tra xem thao tác gộp có tạo ra NaN hay không. Mặc định làFalse. - adapter_names (
list[str], tùy chọn) — Danh sách tên adapter cần được hợp nhất. Nếu là None, tất cả các adapter đang hoạt động sẽ được hợp nhất. Mặc định làNone.
Gộp trọng số của adapter đang hoạt động vào trọng số cơ sở
Phương pháp này tách tất cả các lớp adapter đã hợp nhất khỏi trọng số cơ sở.
Bộ thích ứng nhúng
lớp peft.tuners.hira.Embedding
< source >( base_layer: nn.Moduleadapter_name: strconfig: HiraConfigr: int = 0fan_in_fan_out: bool = False**kwargs )
HiRA forward cho lớp Embedding. Hỗ trợ các adapter hỗn hợp theo batch hoặc một adapter đơn.
get_delta_weight
< source >( adapter )
Tính toán trọng số delta cho adapter đã cho.
merge
< source >( safe_merge: bool = Falseadapter_names: Optional[list[str]] = None )
Tham số
- safe_merge (
bool, tùy chọn) — Nếu là True, thao tác gộp sẽ được thực hiện trên một bản sao của trọng số gốc và kiểm tra các giá trị NaN trước khi gộp trọng số. Điều này hữu ích nếu bạn muốn kiểm tra xem thao tác gộp có tạo ra NaN hay không. Mặc định làFalse. - adapter_names (
list[str], tùy chọn) — Danh sách tên adapter cần được hợp nhất. Nếu là None, tất cả các adapter đang hoạt động sẽ được hợp nhất. Mặc định làNone.
Gộp trọng số của adapter đang hoạt động vào trọng số cơ sở
Phương pháp này tách tất cả các lớp adapter đã hợp nhất khỏi trọng số cơ sở.
Bộ thích ứng tích chập
[[autodoc]] tuners.hira.layer.Conv1d [[autodoc]] tuners.hira.layer.Conv2d [[autodoc]] tuners.hira.layer.ConvNd
Update on GitHub