Transformers documentation
Kiểm tra yêu cầu kéo
Kiểm tra yêu cầu kéo
Khi bạn mở một pull request, CI của Hugging Face sẽ chạy một số kiểm tra mà bắt buộc phải vượt qua trước khi PR của bạn có thể được hợp nhất.
- Khắc phục CI liệt kê các lệnh cần chạy cục bộ để vượt qua các kiểm tra.
- Các phần sau đó mô tả nội dung mà mỗi bước kiểm tra xác thực, chẳng hạn như chất lượng mã và tính nhất quán của kho lưu trữ.
- Tests mô tả các bài kiểm tra được chạy, các danh mục kiểm tra và các bài kiểm tra chậm.
Sửa CI
Trong hầu hết các trường hợp, make style là đủ để vượt qua kiểm tra chất lượng mã, đây là lỗi phổ biến nhất.
make style
Đối với các lỗi về tính nhất quán của kho, bản sao hoặc các tệp được tạo tự động, hãy chạy make fix-repo. Lệnh này sẽ sửa lỗi về kiểu dáng, bản sao, docstring và các tệp được tạo tự động trong một lần chạy.
make fix-repo
Đối với một thay đổi lớn hơn, chuỗi ba lệnh bên dưới bao phủ mọi kiểm tra. Nó nặng nề hơn, nhưng bắt được mọi thứ trước khi bạn đẩy lên.
make fix-repo # auto-fix everything that can be auto-fixed
make typing # check types and model structure, fix any errors manually
make check-repo # verify all checks pass, fix anything that remainsmake typing phát hiện các lỗi kiểu dữ liệu và vi phạm cấu trúc mô hình để bạn sửa thủ công. make check-repo thực hiện một lượt kiểm tra chỉ đọc cuối cùng để bạn xác nhận mọi thứ đã sẵn sàng.
CI thỉnh thoảng không ổn định. Nếu một bước kiểm tra thất bại do nguyên nhân không liên quan đến thay đổi của bạn, hãy liên hệ một người duy trì để chạy lại.
Chất lượng mã
Kiểm tra chất lượng mã bao gồm định dạng, import, kiểm tra kiểu và các quy tắc về cấu trúc mô hình. Nó tương ứng với make fix-repo và make typing.
make style (được bao gồm trong make fix-repo) tự động sửa lỗi lint và định dạng Ruff, thứ tự import trong __init__.py, và tính nhất quán của auto-mapping.
make typing thực hiện kiểm tra kiểu với ty và xác thực các quy tắc TRansFormers (TRF), bao gồm các quy ước đặt tên lớp config và chữ ký của forward(). Lỗi kiểu và vi phạm TRF sẽ báo một số quy tắc cụ thể và phải được sửa thủ công. Các quy tắc này nằm trong kho mlinter. Chạy python -m utils.mlinter --list-rules để xem mọi quy tắc TRF, hoặc python -m utils.mlinter --rule TRFXXX để xem tài liệu đầy đủ cho một quy tắc cụ thể.
Nếu một quy tắc TRF cần ngoại lệ, hãy chọn một trong các tùy chọn sau (xem Áp dụng ngoại lệ cho vi phạm để biết thêm chi tiết).
- Thêm tên model của bạn vào danh sách
allowlist_modelscho quy tắc tương ứng trongutils/mlinter/rules.toml. Sử dụng cách này khi toàn bộ tệp model cần được ngoại lệ. - Thêm
# trf-ignore: TRFXXXtrên cùng dòng với cấu trúc bị đánh dấu, hoặc trên dòng ngay phía trên nó. Sử dụng cách này khi chỉ có một cấu trúc bị đánh dấu cần ngoại lệ.
Tính nhất quán của kho lưu trữ
Kiểm tra tính nhất quán của kho lưu trữ tương tự như make check-repo, ngoại trừ việc nó dừng lại ngay khi gặp lỗi đầu tiên. Nó giữ cho kho lưu trữ nhất quán bên trong giữa các danh mục sau: các đối tượng công khai vẫn có thể nhập được, mã được sao chép vẫn đồng bộ với nguồn gốc của nó, và các tệp được tạo tự động (dummies, doctests, metadata) phản ánh trạng thái hiện tại của mã. Đối với các mô hình mới, nó cũng xác minh rằng mọi lớp mô hình mới đều được đăng ký trong các ánh xạ tự động.
| Danh mục | Những gì được xác thực | Đã tự động sửa? |
|---|---|---|
| Tệp khởi tạo | Các tệp __init__.py trong src/transformers/models/ đã được cập nhật | make fix-repo |
| Bản sao và mô-đun | Các khối # Copied from khớp với nguồn và các tệp được tạo theo mô-đun đã được cập nhật | make fix-repo |
| Docstring và tài liệu | Chuỗi mô tả đối số khớp với chữ ký hàm và mục lục tài liệu | make fix-repo |
| Tệp được tạo tự động | Dummies, kiểu hóa pipeline, danh sách doctest, metadata, bảng phụ thuộc | make fix-repo |
| Kiểm tra hợp lệ cấu hình | Các lớp Config có checkpoint hợp lệ trong docstring và các thuộc tính config khớp với tệp modeling | Thủ công |
| Gán người đánh giá | Mọi thư mục mô hình và mọi quy tắc trong tệp người xem xét đều được chuyển đến một người xem xét | Thủ công |
Gán người đánh giá
.github/scripts/codeowners_for_review_action ghi lại ai xem xét những tệp nào.
Quyền sở hữu được xác định theo từng tệp, ưu tiên theo mức độ cụ thể nhất trước.
| Nơi | Có vẻ | Sử dụng cho |
|---|---|---|
| Tệp mô hình | # Reviewers: @login trong khối chú thích đầu tiên của modular_<model>.py hoặc modeling_<model>.py | một mô hình cần người khác ngoài chủ sở hữu chế độ của nó. Bộ chuyển đổi mô-đun sao chép phần tiêu đề vào tệp mô hình hóa được tạo, vì vậy thẻ vẫn tồn tại sau khi tạo lại |
| Quy tắc đường dẫn | /src/transformers/<area>/ @login trong .github/scripts/codeowners_for_review_action | bất kỳ thứ gì không phải là mô hình |
| Bảng chế độ | @@modality/vision @login, trong cùng một tệp | mọi model có trang tài liệu nằm trong phần đó của docs/source/en/_toctree.yml |
| Phương án dự phòng | * @Rocketknight1 @ArthurZucker | bất kỳ điều gì khác không được yêu cầu |
Một model mới không cần mục nào ở bất kỳ đâu: việc thêm trang tài liệu của nó vào _toctree.yml, vốn đã được kiểm tra mục lục tài liệu yêu cầu, sẽ đặt nó vào một modality, và bảng modality sẽ bao phủ nó từ đó.
make check-repository-consistency chạy utils/check_reviewers.py, lệnh này sẽ thất bại khi một model không có ai phụ trách ngoài catch-all, khi một rule không còn khớp với file nào, hoặc khi bảng modality không khớp với mục lục. Resolver của nó không phải là dependency của transformers; nó được liệt kê trong utils/checkers-requirements.txt, và trình chạy checker sẽ cài đặt nó trong môi trường ở lần chạy đầu tiên. Nếu quá trình cài đặt không thể diễn ra — ví dụ khi offline — lệnh kiểm tra sẽ báo cáo điều này và cho qua thay vì chặn bạn.
Các đường dẫn nằm ngoài src/transformers/models mà không có owner sẽ được báo cáo dưới dạng ghi chú; liệt kê chúng bằng:
python utils/check_reviewers.py --strict
Kiểm thử
CI chạy một tập con các bài kiểm tra được nhắm mục tiêu dựa trên những gì PR của bạn thay đổi. CI chạy các bài kiểm tra theo thứ tự ngẫu nhiên hóa một phần bằng pytest-random-order để bắt các bài kiểm tra có liên kết. Chạy in hạt ngẫu nhiên (random seed) ở đầu để bạn có thể phát lại cùng một thứ tự bằng --random-order-seed=<seed>.
Nếu một bài kiểm tra chạy thành công cục bộ trên GPU nhưng thất bại trong CI, hãy đặt TRANSFORMERS_TEST_DEVICE="cpu" để kiểm tra xem bạn có thể tái hiện lỗi trên CPU hay không.
TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -vCác phần bên dưới giải thích cách chọn bài kiểm tra hoạt động, những công việc nào được chạy và cách xử lý các bài kiểm tra chậm.
Chọn kiểm thử
CI không chạy bộ kiểm thử đầy đủ trên mọi PR. CI bỏ qua các kiểm thử được trang trí bằng @slow trên mọi PR, và một người duy trì sẽ kích hoạt chúng trên GPU khi PR đã được đưa vào xem xét.
utils/tests_fetcher.py theo dõi các phụ thuộc import từ các tệp bạn đã thay đổi để xác định các bài kiểm tra bị ảnh hưởng, và chỉ chạy những bài đó. Nó cũng phát hiện các lỗi hồi quy ở các model khác khi bạn chạm vào các tiện ích dùng chung. Bộ lấy dữ liệu sẽ in ra các tệp đã thay đổi và các bài kiểm tra bị ảnh hưởng, sau đó ghi danh sách vào tests_torch_test_list.txt.
Sử dụng fetcher để tái hiện chính xác những gì CI chạy.
python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)Việc thay đổi các tệp lõi như
modeling_utils.pyhoặcgeneration/utils.pysẽ kích hoạt tất cả các bài kiểm tra mô hình, chứ không chỉ tập con bị ảnh hưởng.
Bạn cũng có thể chạy mọi bài kiểm tra cho mô hình của mình một cách không điều kiện. Việc chạy trực tiếp là một bước kiểm tra hợp lệ cục bộ nhanh hơn, nhưng nó sẽ không phát hiện được các lỗi hồi quy ở các mô hình khác do mã dùng chung mà bạn đã chỉnh sửa gây ra.
pytest tests/models/my_model/ -v
Các danh mục công việc kiểm thử
Các bài kiểm thử được chia thành các công việc CI song song, và mỗi công việc sẽ chọn các tệp theo mẫu đường dẫn. Các công việc liên quan đến một PR của model là:
tests_torch: các bài kiểm tra mô hình (tests/models/*/test_modeling_*.py)tests_tokenization: các bài kiểm tra tokenizer (tests/models/*/test_tokenization_*.py)tests_processors: các bài kiểm tra processor và feature extractor (tests/models/*/test_(processing|image_processing|feature_extractor)_*.py)tests_generate: các bài kiểm tra sinhpipelines_torch: các bài kiểm tra pipelinetests_training_ci: các bài kiểm tra vòng lặp huấn luyệntests_tensor_parallel_ci: các bài kiểm tra song song tensortests_fsdp_ci: các bài kiểm tra FSDP
Kiểm thử chậm
Các lần chạy CI thông thường sẽ bỏ qua các test được đánh dấu bằng @slow. Chúng tải các checkpoint thực hoặc cần nhiều tài nguyên tính toán, do đó được chạy trên các instance GPU, và các maintainer sẽ kích hoạt chúng khi PR của bạn đang được xem xét.
Các bài kiểm tra chạy chậm được thực hiện trên NVIDIA A10, và kết quả số học có thể thay đổi nhẹ giữa phần cứng CI và máy cục bộ của bạn. Người duy trì thường điều chỉnh các giá trị đó trong các bài kiểm tra khi cần thiết khi thêm một mô hình mới.
Chạy các bài kiểm tra chậm cục bộ bằng lệnh bên dưới.
RUN_SLOW=1 python -m pytest tests/models/my_model/ -v
Xây dựng tài liệu
Job build_pr_documentation sẽ build và tạo bản xem trước của tài liệu. Một bot sẽ đăng liên kết xem trước trong PR của bạn, và check này phải pass trước khi merge. Phần lớn các lỗi là do thiếu entry trong toctree. Để build tài liệu cục bộ, hãy xem README.md trong thư mục docs.
# Sao chép từ cú pháp
Đối với các mô hình mới, luôn ưu tiên luồng làm việc modular (
modular_*.py) hơn là# Copied from. Tránh sử dụng# Copied frombất cứ khi nào có thể.
Cơ chế # Copied from giữ cho mã được sao chép đồng bộ với nguồn gốc của nó. Khi make fix-repo chạy, nó kiểm tra mọi khối # Copied from và cập nhật chúng để khớp với bản gốc, do đó các chỉnh sửa bên trong một khối # Copied from sẽ bị ghi đè. Hãy chỉnh sửa nguồn gốc và để make fix-repo lan truyền thay đổi đó.
Các dạng cơ bản của # Copied from bao gồm những mục sau.
# Copied from transformers.models.bert.modeling_bert.BertSelfOutput
# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert->Roberta
# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert->MobileBert all-casingCú pháp with model->newModel áp dụng các thay thế chuỗi sau khi sao chép. Tách nhiều thay thế bằng dấu phẩy, chúng được áp dụng từ trái sang phải. Tùy chọn all-casing thay thế mọi biến thể kiểu chữ cùng lúc (Bert, bert, BERT trở thành MobileBert, mobilebert, MOBILEBERT).