Transformers documentation

Kiểm tra yêu cầu kéo

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

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.

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 remains

make 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_models cho quy tắc tương ứng trong utils/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: TRFXXX trê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ụcNhững gì được xác thựcĐã tự động sửa?
Tệp khởi tạoCác tệp __init__.py trong src/transformers/models/ đã được cập nhậtmake fix-repo
Bản sao và mô-đunCá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ậtmake fix-repo
Docstring và tài liệuChuỗi mô tả đối số khớp với chữ ký hàm và mục lục tài liệumake fix-repo
Tệp được tạo tự độngDummies, kiểu hóa pipeline, danh sách doctest, metadata, bảng phụ thuộcmake fix-repo
Kiểm tra hợp lệ cấu hìnhCá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 modelingThủ 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étThủ 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ơiCó 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>.pymộ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_actionbất kỳ thứ gì không phải là mô hình
Bảng chế độ@@modality/vision @login, trong cùng một tệpmọ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 @ArthurZuckerbấ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/ -v

Cá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.py hoặc generation/utils.py sẽ 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 sinh
  • pipelines_torch: các bài kiểm tra pipeline
  • tests_training_ci: các bài kiểm tra vòng lặp huấn luyện
  • tests_tensor_parallel_ci: các bài kiểm tra song song tensor
  • tests_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 from bấ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-casing

Cú 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).

Update on GitHub