PEFT documentation
Tham quan nhanh
Tham quan nhanh
PEFT cung cấp các phương pháp hiệu quả về tham số để tinh chỉnh các mô hình tiền huấn luyện lớn. Hệ thống truyền thống là tinh chỉnh tất cả các tham số của mô hình cho từng tác vụ hạ nguồn, nhưng điều này ngày càng trở nên tốn kém và không thực tế do số lượng tham số khổng lồ trong các mô hình hiện nay. Thay vào đó, việc huấn luyện một số lượng nhỏ hơn các tham số prompt hoặc sử dụng phương pháp tham số hóa lại như thích ứng hạng thấp (LoRA) để giảm số lượng tham số có thể huấn luyện sẽ hiệu quả hơn.

Cuộc tham quan nhanh này sẽ giới thiệu cho bạn các tính năng chính của PEFT và cách bạn có thể huấn luyện hoặc chạy suy luận trên các mô hình lớn mà thông thường không thể tiếp cận được trên các thiết bị tiêu dùng.
Cấu hình PEFT và mô hình
Với bất kỳ phương pháp PEFT nào, bạn cần tạo một cấu hình chứa tất cả các tham số quy định cách áp dụng phương pháp PEFT, quan trọng nhất là các lớp của mô hình hiện có cần nhắm đến bằng các tham số có thể huấn luyện. Sau khi cấu hình được thiết lập, truyền nó cùng với mô hình cơ sở vào hàm get_peft_model() để tạo một PeftModel có thể huấn luyện.
Hãy dùng LoRA làm ví dụ nhưng chỉ thảo luận về các tham số phổ biến - bạn có thể muốn sử dụng một trong nhiều phương pháp PEFT khác. Cấu hình thường bao gồm những điều sau:
target_modules: các module của mô hình cơ sở cần thích ứngtask_type(mặc định:None, xem cácTaskTypekhả dụng): bản chất của tác vụ được huấn luyện; nếu được cung cấp, có thể giúp tự động lưu các lớp liên quan cùng với trọng số adapter hoặc cảnh báo bạn về các sự không tương thíchinference_mode(mặc định:False): cho biết bạn có đang sử dụng mô hình để suy luận hay không
Tùy thuộc vào phương pháp PEFT bạn chọn, bạn sẽ thêm các tham số cụ thể, chẳng hạn như xác định kích thước của các ma trận cập nhật. Dưới đây là một ví dụ về cấu hình mà bạn có thể gặp trong thực tế:
from peft import LoraConfig, TaskType
peft_config = LoraConfig(target_modules=["q_proj"], task_type=TaskType.CAUSAL_LM, inference_mode=False, r=8, lora_alpha=32, lora_dropout=0.1)Xem hướng dẫn cấu hình để biết thêm chi tiết về cách cấu hình PEFT hoạt động bên trong.
Sau khi thiết lập LoraConfig, hãy tạo một PeftModel bằng hàm get_peft_model(). Hàm này nhận một mô hình cơ sở - bạn có thể (nhưng không bắt buộc) tải từ thư viện Transformers - và LoraConfig chứa các tham số để cấu hình mô hình cho việc huấn luyện với LoRA.
Tải mô hình cơ sở mà bạn muốn tinh chỉnh.
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("meta-llama/Llama-3.2-1B")Bây giờ hãy bọc model cơ sở và peft_config bằng hàm get_peft_model() để tạo một PeftModel.
Wrapping có nghĩa là PEFT thay thế các lớp được nhắm tới (ở đây: tất cả các lớp q_proj) bằng lớp cụ thể cho adapter, tương ứng với kiểu của lớp đích. Vì chúng ta đang làm việc với các lớp tuyến tính, trong trường hợp này sẽ là một lớp lora.Linear. Lưu ý rằng những thay đổi này được thực hiện tại chỗ để tiết kiệm bộ nhớ, do đó mô hình cơ sở của bạn đã bị thay đổi.
Lưu ý rằng chúng ta chỉ đã chỉ định q_proj nhưng thực tế chúng ta đang nhắm đến tất cả các lớp model.layers[:].self_attn.q_proj. Điều này là do PEFT tìm kiếm các hậu tố khớp theo mặc định. Truyền một chuỗi chứa biểu thức chính quy nếu bạn muốn nhắm đến các mẫu lớp phức tạp hơn.


Tầng của mô hình cơ sở sẽ được bọc lại, giữ nguyên và không được huấn luyện trong khi các trọng số mới, có thể huấn luyện được, được thêm vào và kết hợp. Cách các trọng số mới này được cấu trúc và kết hợp với trọng số của mô hình cơ sở là một phần quan trọng tạo nên sự khác biệt giữa các phương pháp PEFT khác nhau.
Trước khi bắt đầu huấn luyện, hãy chạy một lệnh kiểm tra sức khỏe để xác nhận trạng thái của adapter và kiểm tra số lượng tham số có thể huấn luyện được.
from peft import get_peft_model, LoraConfig
peft_config = LoraConfig() # or your other PEFT method of choice
peft_model = get_peft_model(model, peft_config)
peft_model.print_healthcheck()Healthcheck bao gồm tỷ lệ tham số có thể huấn luyện cùng với trạng thái adapter, cấu hình mô hình và môi trường.
Chạy kiểm tra sức khỏe
Sử dụng print_healthcheck() để xác định các trạng thái đáng ngờ, chẳng hạn như adapter đã được hợp nhất hoặc không nhất quán, và để tạo báo cáo ngắn gọn cho báo cáo lỗi.
peft_model.print_healthcheck()
Điều này nên hiển thị một nội dung như:
PEFT healthcheck
Model:
ID: meta-llama/Llama-3.2-1B, type: LlamaForCausalLM, adapters: default (LORA)
Environment:
peft: 0.21.0, transformers: 5.18.0.dev0, torch: 2.14.0+cu130, Python: 3.13.9
Runtime:
training: True, devices: cpu, dtypes: bfloat16=1,235,814,400, float32=851,968, activation checkpointing: False
Parameters:
trainable: 851,968, total: 1,236,666,368, percent trainable: 0.0689%, adapter layers: 32
State:
adapter is enabled: True, active: default, merged: none
Layer types:
default:
lora.Linear=32Đầu ra in ra có thể thay đổi, không nên cố gắng phân tích nó. Để sử dụng theo chương trình, hãy gọi healthcheck() thay thế, hàm này trả về cùng thông tin dưới dạng từ điển có thể chuỗi hóa JSON.
Đó là tất cả 🎉! Bây giờ bạn có thể huấn luyện mô hình bằng Trainer của Transformers, Accelerate, hoặc bất kỳ vòng lặp huấn luyện PyTorch tùy chỉnh nào.
Ví dụ, để huấn luyện với lớp Trainer, hãy thiết lập một lớp TrainingArguments với một số siêu tham số huấn luyện.
training_args = TrainingArguments(
output_dir="your-name/meta-llama/my-llama3.2-adapter",
learning_rate=1e-3,
per_device_train_batch_size=32,
per_device_eval_batch_size=32,
num_train_epochs=2,
weight_decay=0.01,
eval_strategy="epoch",
save_strategy="epoch",
load_best_model_at_end=True,
)Truyền model, các đối số huấn luyện, tập dữ liệu, tokenizer và bất kỳ thành phần cần thiết nào khác vào Trainer, sau đó gọi train để bắt đầu huấn luyện.
trainer = Trainer(
model=peft_model,
args=training_args,
train_dataset=tokenized_datasets["train"],
eval_dataset=tokenized_datasets["test"],
data_collator=data_collator,
compute_metrics=compute_metrics,
)
trainer.train()Lưu mô hình
Sau khi mô hình của bạn hoàn tất huấn luyện, bạn có thể lưu mô hình vào một thư mục bằng cách sử dụng hàm save_pretrained().
peft_model.save_pretrained("output_dir")Bạn cũng có thể lưu mô hình của mình lên Hub (đảm bảo bạn đã đăng nhập vào tài khoản Hugging Face trước) bằng hàm push_to_hub.
from huggingface_hub import notebook_login
notebook_login()
peft_model.push_to_hub("your-name/my-llama3.2-adapter")Cả hai phương pháp chỉ lưu trữ các trọng số PEFT bổ sung đã được huấn luyện, do đó việc lưu trữ, truyền tải và nạp lại cực kỳ hiệu quả. Ví dụ, mô hình facebook/opt-350m này được huấn luyện với LoRA chỉ chứa hai tệp: adapter_config.json và adapter_model.safetensors. Tệp adapter_model.safetensors chỉ có dung lượng 6,3MB!
Suy luận
Xem tài liệu tham khảo API AutoPeftModel để có danh sách đầy đủ các lớp
AutoPeftModelkhả dụng.
Dễ dàng tải bất kỳ mô hình PEFT đã được huấn luyện nào để suy luận bằng lớp AutoPeftModel và phương thức from_pretrained:
from peft import AutoPeftModelForCausalLM
from transformers import AutoTokenizer
import torch
device = torch.accelerator.current_accelerator().type if hasattr(torch, "accelerator") else "cuda"
peft_model = AutoPeftModelForCausalLM.from_pretrained("ybelkada/opt-350m-lora")
tokenizer = AutoTokenizer.from_pretrained("facebook/opt-350m")
peft_model = peft_model.to(device)
peft_model.eval()
inputs = tokenizer("Preheat the oven to 350 degrees and place the cookie dough", return_tensors="pt")
outputs = peft_model.generate(input_ids=inputs["input_ids"].to(peft_model.device), max_new_tokens=50)
print(tokenizer.batch_decode(outputs.detach().cpu().numpy(), skip_special_tokens=True)[0])
"Preheat the oven to 350 degrees and place the cookie dough in the center of the oven. In a large bowl, combine the flour, baking powder, baking soda, salt, and cinnamon. In a separate bowl, combine the egg yolks, sugar, and vanilla."Đối với các tác vụ khác không được hỗ trợ rõ ràng bằng lớp AutoPeftModelFor - chẳng hạn như nhận dạng giọng nói tự động - bạn vẫn có thể sử dụng lớp AutoPeftModel cơ bản để tải mô hình cho tác vụ đó.
from peft import AutoPeftModel
peft_model = AutoPeftModel.from_pretrained("smangrul/openai-whisper-large-v2-LORA-colab")Cách tổng quát nhất để nạp một bộ thích ứng PEFT đã được huấn luyện vào một mô hình là sử dụng from_pretrained():
from transformers import AutoPeftModelForCausalLM
from peft import PeftModel
base_model = AutoModelForCausalLM.from_pretrained("meta-llama/llama3.2-1B")
peft_model = PeftModel.from_pretrained(base_model, "my-user/my-llama-adapter") # you can also pass a directory instead of a hub pathNhiều bộ thích ứng
PEFT hỗ trợ cài đặt nhiều adapter (cùng một loại, trong tài liệu này là LoRA) lên trên một mô hình cơ sở. Khi bạn gọi get_peft_model, chỉ có một adapter có tên là "default", nhưng bạn có thể thêm bao nhiêu adapter bổ sung tùy ý bằng cách gọi peft_model.add_adapter(adapter_name=...).
Cách này hoạt động vì lớp được bọc thực sự có một bộ trọng số có thể huấn luyện riêng biệt cho mỗi tên adapter. Không phải adapter nào cũng được kích hoạt và có thể huấn luyện theo mặc định. Bạn phải bật adapter theo tên một cách rõ ràng trước khi chúng được kích hoạt. Điều này cho phép bạn nhanh chóng chuyển đổi giữa các adapter khi cần kiến thức cụ thể cho từng tác vụ hoặc phục vụ các trường hợp sử dụng khác nhau trên cùng một mô hình.

Hãy nhớ gọi peft_model.set_adapter(<adapter_name>) trước để kích hoạt adapter.
Ví dụ nhanh:
peft_model.add_adapter(adapter_name='new_adapter')
peft_model.set_adapter('new_adapter')Các bước tiếp theo
Giờ đây, khi bạn đã biết cách huấn luyện một mô hình bằng một trong các phương pháp PEFT, chúng tôi khuyến khích bạn thử nghiệm một số phương pháp khác như prompt tuning. Các bước rất tương tự với những gì được trình bày trong quicktour:
- chuẩn bị một PeftConfig cho một phương pháp PEFT, ví dụ như một LoraConfig hoặc một cấu hình khác (xem tổng quan về phương pháp)
- sử dụng phương thức get_peft_model() để tạo một PeftModel từ cấu hình và mô hình cơ sở
Sau đó, bạn có thể huấn luyện nó theo bất kỳ cách nào bạn muốn! Để tải một mô hình PEFT cho suy luận, bạn có thể sử dụng lớp AutoPeftModel.
Bạn cũng có thể xem các hướng dẫn về tác vụ nếu bạn quan tâm đến việc huấn luyện mô hình bằng một phương pháp PEFT khác cho một tác vụ cụ thể như phân đoạn ngữ nghĩa, nhận dạng giọng nói tự động đa ngôn ngữ, DreamBooth, phân loại token, và nhiều hơn nữa.
Update on GitHub