PEFT documentation

Đóng góp cho PEFT

PEFT

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.21.0).

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

Đóng góp cho PEFT

Chúng tôi rất vui khi nhận được các đóng góp cho PEFT. Nếu bạn có kế hoạch đóng góp, vui lòng đọc tài liệu này để quá trình diễn ra suôn sẻ nhất có thể.

Thảo luận và nhận được sự phê duyệt trước khi mở PR

Trước khi mở một pull request (kể cả bản nháp), hãy mở hoặc tìm một issue trong huggingface/peft và thảo luận về đóng góp bạn đề xuất. Nếu đã có một issue tồn tại và ai đó đang làm việc trên nó, đã tuyên bố ý định làm việc trên nó, hoặc đã có một PR đang mở, bạn không nên gửi một PR riêng biệt. Hãy chờ một người duy trì PEFT hoặc thành viên Hugging Face phê duyệt rõ ràng đề xuất. Nếu bạn mở một issue, hãy giữ độ dài và độ phức tạp của mô tả tương xứng với độ phức tạp của issue. Thường thì, một mô tả ngắn kèm theo mã tái hiện vấn đề có giá trị hơn một mô tả dài.

Bình luận phê duyệt chứa thông điệp /peft-triage approved. Nó có thể kèm theo tên người đóng góp được phân công, ví dụ /peft-triage approved username hoặc /peft-triage approved @username. Việc mở một PR cho một issue mà bạn không được phân công sẽ dẫn đến việc PR đó bị đóng.

Liên kết issue mở đã được phê duyệt trong mô tả PR của bạn bằng #123, huggingface/peft#123, hoặc https://github.com/huggingface/peft/issues/123. Ngoại lệ duy nhất, các maintainer có thể chỉ định một số cuộc thảo luận dài hạn cụ thể có thể được tham chiếu bằng URL GitHub đầy đủ mà không cần bình luận phê duyệt riêng. Nếu bạn tham chiếu nhiều issue hoặc cuộc thảo luận, chỉ cần một tham chiếu hợp lệ là đủ.

Quy trình tự động sẽ kiểm tra các PR để xác định xem chúng có liên kết đến các issue hoặc thảo luận mở đã được phê duyệt hay không. Các PR không có tham chiếu hợp lệ sẽ bị đóng tự động kèm theo giải thích. Bạn có thể xin phê duyệt issue, cập nhật mô tả PR và mở lại cùng một PR đó; vui lòng không tạo PR thay thế. Nếu bạn cho rằng PR của mình bị đóng sai, hãy ping các maintainer trên PR.

Bot stale độc lập vẫn có thể đóng các mục không hoạt động, ngay cả khi được gắn nhãn triaged. Nếu bạn cảm thấy các nhà duy trì đã bỏ qua đóng góp của mình, bạn có thể nhắc họ, nhưng không sớm hơn hai tuần kể từ khi không có hoạt động.

Cài đặt

Thực hiện các bước sau để bắt đầu đóng góp:

Fork repository bằng cách nhấp vào nút ‘Fork’ trên trang của repository. Thao tác này tạo ra một bản sao của mã nguồn dưới tài khoản GitHub của bạn.
Clone bản fork của bạn về ổ đĩa cục bộ và thêm kho cơ sở dưới dạng remote. Lệnh sau đây giả định rằng bạn đã tải khóa SSH công khai lên GitHub. Xem hướng dẫn sau để biết thêm thông tin.
```
git clone git@github.com:<your Github handle>/peft.git
cd peft
git remote add upstream https://github.com/huggingface/peft.git
```
Tạo một nhánh mới để lưu các thay đổi phát triển của bạn, và thực hiện điều này cho mọi PR mới mà bạn làm việc.

Bắt đầu bằng cách đồng bộ hóa nhánh main của bạn với nhánh upstream/main (xem thêm chi tiết trong Tài liệu GitHub):
```
git checkout main
git fetch upstream
git merge upstream/main
```
Khi nhánh main của bạn đã được đồng bộ, hãy tạo một nhánh mới từ nó:
```
git checkout -b a-descriptive-name-for-my-changes
```
Không làm việc trên nhánh main.
Thiết lập môi trường phát triển bằng cách chạy lệnh sau trong conda hoặc môi trường ảo mà bạn đã tạo để làm việc với thư viện này:
```
pip install -e ".[test]"
```
(Nếu PEFT đã được cài đặt trong môi trường ảo, hãy gỡ bỏ nó bằng pip uninstall peft trước khi cài đặt lại.)

Nếu bạn mới bắt đầu tạo pull request, hãy làm theo hướng dẫn Creating a pull request của GitHub.

Kiểm tra và kiểm tra chất lượng mã

Bất kể loại đóng góp nào (trừ khi chỉ liên quan đến tài liệu), bạn nên chạy các bài kiểm thử và kiểm tra chất lượng mã trước khi tạo PR để đảm bảo đóng góp của bạn không làm hỏng bất kỳ thứ gì và tuân thủ các tiêu chuẩn của dự án.

Chạy kiểm thử và kiểm tra

Chúng tôi cung cấp một Makefile để thực thi các bài kiểm tra cần thiết. Chạy mã bên dưới cho bài kiểm tra đơn vị:

make test

Chạy một trong các lệnh sau để chỉ kiểm tra hoặc kiểm tra và sửa chất lượng cũng như phong cách mã:

make quality  # just check
make style  # check and fix

Chạy make quality cũng sẽ kiểm tra xem tất cả các method/class từ public API của PEFT (tức là mọi thứ được đề cập trong peft.__all__) có được đề cập trong tài liệu hay không. Những lỗi này không thể được sửa bằng make style, bạn cần đảm bảo rằng các mục mới trong public API được ghi tài liệu trong docs để khắc phục lỗi này.

Bạn cũng có thể thiết lập pre-commit để tự động chạy các bản sửa này dưới dạng Git commit hooks.

$ pip install pre-commit
$ pre-commit install

Việc chạy tất cả các bài kiểm tra có thể mất một thời gian, nên trong quá trình phát triển, việc chỉ chạy các bài kiểm tra cụ thể cho thay đổi của bạn có thể hiệu quả hơn, ví dụ thông qua:

pytest tests/<test-file-name> -k <name-of-test>

Điều này nên hoàn thành nhanh hơn nhiều và cho phép lặp lại nhanh hơn.

Thêm các bài kiểm thử

Để có hướng dẫn chung về việc thêm các bài kiểm tra mới, hãy xem tests/README.md.

Nếu thay đổi của bạn chỉ áp dụng cho một cài đặt phần cứng cụ thể (ví dụ: yêu cầu CUDA), hãy xem tests/test_gpu_examples.py và tests/test_common_gpu.py để xem liệu có nên thêm các bài kiểm thử ở đó hay không. Nếu thay đổi của bạn có thể ảnh hưởng đến việc lưu và tải mô hình, vui lòng chạy các bài kiểm thử với cờ --regression để kích hoạt các bài kiểm thử hồi quy.

PR cũ

Trong quá trình bạn làm việc trên PR của mình, mã nguồn cơ bản có thể thay đổi do các thay đổi khác được hợp nhất. Nếu điều đó xảy ra – đặc biệt là khi có xung đột hợp nhất – vui lòng cập nhật nhánh của bạn với những thay đổi mới nhất. Thao tác này có thể là merge hoặc rebase, và chúng tôi sẽ squash và merge PR khi nó đã sẵn sàng. Tránh force push để việc xem xét dễ dàng hơn.

Mô tả PR

Khi mở một PR, vui lòng cung cấp một mô tả rõ ràng về thay đổi bạn đang đề xuất và tham chiếu đến issue đã được phê duyệt như đã mô tả ở trên. Nếu liên quan đến các issue hoặc PR khác, vui lòng tham chiếu đến chúng. Việc cung cấp một mô tả tốt không chỉ giúp các reviewer xem xét mã của bạn tốt hơn và nhanh hơn, mà còn có thể được sử dụng sau này (làm cơ sở) cho thông báo commit, hỗ trợ việc bảo trì dự án trong dài hạn.

Giữ độ dài và mức độ phức tạp của mô tả PR tương xứng với thay đổi. Chúng ta không cần mười đoạn giải thích cho một thay đổi đơn giản chỉ một dòng. Đừng lặp lại những gì đã rõ ràng khi nhìn vào diff (ví dụ: “Đã sửa lỗi chính tả trong ‘foobaar’”).

Nếu mã của bạn thực hiện một số thay đổi không đơn giản, việc thêm chú thích vào mã để giải thích những thay đổi đó cũng là một ý tưởng hay. Ví dụ, nếu bạn phải lặp lại việc triển khai nhiều lần vì cách rõ ràng nhất không hoạt động, đó là dấu hiệu tốt cho thấy cần có chú thích mã.

Nếu liên quan, hãy chỉ ra cách bạn đã kiểm tra thay đổi, ví dụ bằng cách hiển thị lệnh kiểm thử pytest hoặc mã tái hiện.

Phản hồi từ người đánh giá

Sau khi bạn gửi PR, một người duy trì thường sẽ phản hồi trong vòng vài ngày. Nếu bạn không nhận được phản hồi nào trong hai tuần, có thể PR của bạn đã bị bỏ sót; lúc đó bạn có thể nhắc các người duy trì, nhưng không nên làm điều này sớm hơn.

Nếu người đánh giá đưa ra các bình luận trực tiếp, đừng đánh dấu chúng là đã giải quyết nếu bạn đã xử lý chúng. Hãy để các bình luận này ở trạng thái mở, vì chúng giúp người đánh giá tiếp tục công việc của họ.

Sau khi xử lý phản hồi từ người đánh giá, hãy thông báo cho người đánh giá để họ biết rằng PR đã sẵn sàng để được xem xét.

Sửa lỗi

Vui lòng mô tả các tình huống dẫn đến lỗi. Nếu đã có issue tồn tại, vui lòng liên kết đến issue đó (ví dụ: “Resolves #12345”).

Lý tưởng nhất là khi một bản sửa lỗi được cung cấp, nó cần đi kèm với một bài kiểm tra cho lỗi đó. Bài kiểm tra phải thất bại với mã hiện tại và thành công với bản sửa lỗi. Thêm một chú thích vào bài kiểm tra để tham chiếu đến vấn đề hoặc PR. Nếu không có bài kiểm tra, việc ngăn chặn các lỗi hồi quy trong tương lai sẽ khó khăn hơn.

Cải thiện tài liệu

Chúng tôi rất vui khi nhận được các bản sửa lỗi cho liên kết bị hỏng và tài liệu bị thiếu hoặc không rõ ràng. Việc chăm chút cho các ví dụ, đảm bảo chúng luôn cập nhật và chạy ổn định trong môi trường thay đổi nhanh chóng này cũng được đánh giá cao.

Vui lòng không gửi pull request chỉ để sửa lỗi chính tả, vì những thay đổi này thường tạo ra nhiều công việc hơn là tiết kiệm. Những thay đổi như vậy nên được kết hợp với các bản sửa lỗi có ý nghĩa hơn (chẳng hạn như sửa các liên kết bị hỏng hoặc mở rộng/cập nhật tài liệu).

Thêm một phương pháp tinh chỉnh PEFT mới

Các phương pháp tinh chỉnh hiệu quả theo tham số mới liên tục được phát triển. Nếu bạn muốn thêm một phương pháp mới đầy triển vọng vào PEFT, vui lòng làm theo các bước sau.

Nếu bạn không phải là tác giả của bài báo gốc, hãy kiểm tra các bản triển khai hiện có và xác nhận lại với các tác giả rằng họ không có kế hoạch tự gửi PR.
Mở một issue đề xuất và chờ sự phê duyệt rõ ràng như đã mô tả ở trên, trước khi bắt đầu công việc tích hợp lõi được liệt kê bên dưới.
Kiểm tra các commit gần đây để xem các phương pháp PEFT mới được thêm vào, nhằm lấy cảm hứng.
Sau khi đề xuất được phê duyệt, có thể hữu ích khi mở một PR bản nháp sớm ngay khi phương pháp về cơ bản đã hoạt động và các bài kiểm tra đầu tiên đạt yêu cầu, sau đó yêu cầu phản hồi. Tham chiếu đến issue đã được phê duyệt trong phần mô tả của PR bản nháp.

Tích hợp cốt lõi của một phương pháp PEFT mới

PR đầy đủ để thêm một phương pháp PEFT mới

Đảm bảo rằng các đối số cấu hình đặc thù cho phương pháp được đặt tên và giải thích rõ ràng, không giả định rằng người dùng đã nắm vững nội dung bài báo.
Tuân theo các quy ước đặt tên và viết mã của PEFT.
Đảm bảo rằng bạn không vô tình kiểm tra (check-in) các thay đổi không liên quan, ví dụ như trình định dạng mã (code formatter) thay đổi các tệp không liên quan.
Nếu một số lựa chọn triển khai không đơn giản, hãy ghi chú chúng bằng một chú thích trong mã.
Hoàn thành bộ kiểm thử đầy đủ (test_config.py, test_decoder_models.py, v.v.) bằng cách thêm phương pháp PEFT vào ma trận kiểm thử. Đảm bảo rằng các kiểm thử chạy thành công.
Thêm tài liệu vào docs/source/package_reference/ với phần giải thích ngắn gọn, liên kết đến bài báo, đoạn mã minh họa cách sử dụng và các khối autodoc. Giải thích ưu điểm và nhược điểm so với các phương pháp khác như LoRA. Đăng ký trang tài liệu đó trong docs/source/_toctree.yml.
Thêm một ví dụ có thể chạy dưới examples/ (có thể là bản sao của một ví dụ hiện có), kèm theo một README.md ngắn.
Kiểm tra các benchmark trong method_comparison/ và thêm các cài đặt thí nghiệm cho phương pháp mới của bạn. Đây là nơi tốt để kiểm tra tính hợp lý xem phương pháp PEFT có được huấn luyện như mong đợi hay không. Bao gồm một hoặc hai cấu hình benchmark hợp lý (một cấu hình mặc định, một cấu hình được tối ưu hóa cho benchmark).
Khuyến nghị: Thêm hỗ trợ lượng tử hóa tổng quát. Thay vì phải thêm rõ ràng các kiểu lớp lượng tử hóa cho từng phương pháp lượng tử hóa, hãy hỗ trợ lượng tử hóa tổng quát. Ví dụ, hãy xem cách triển khai trong BOFT. Mở rộng https://github.com/huggingface/peft/blob/main/tests/test_quantization.py bằng cách thêm phương pháp PEFT của bạn vào đó. Hãy nhờ các nhà bảo trì hỗ trợ nếu cần.

Thực hiện các thay đổi đối với các phương pháp PEFT hiện có

Nếu bạn thực hiện một thay đổi đối với một phương pháp PEFT có khả năng làm thay đổi đầu ra của nó, do đó làm cho các checkpoint đã được huấn luyện trở nên không còn hợp lệ, chúng ta cần thực hiện các biện pháp phòng ngừa bổ sung. Vui lòng kiểm tra mô tả tại https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md để biết thêm chi tiết. Các hướng dẫn ở đó được thiết kế cho cả con người và AI.

Thêm các tính năng khác

Trước tiên, hãy mở một issue trên GitHub với đề xuất thêm tính năng mới và chờ sự phê duyệt rõ ràng như đã mô tả ở trên. Bằng cách này, bạn có thể thảo luận với các maintainer xem việc thêm tính năng đó có hợp lý hay không trước khi dành quá nhiều thời gian để triển khai nó.

Các tính năng mới thường nên đi kèm với các bài kiểm thử và tài liệu hoặc ví dụ. Nếu thiếu những yếu tố này, người dùng sẽ khó phát hiện ra tính năng mới thú vị của bạn.

Các thay đổi đối với mã nguồn cần được triển khai theo cách tương thích ngược. Ví dụ, mã hiện có phải tiếp tục hoạt động giống như trước sau khi tính năng được hợp nhất.

Update on GitHub

←torch.compile Xử lý sự cố→