Đóng góp cho 🤗 Transformers

Quy tắc đóng góp

Có hai cách để mở một PR: sửa một issue đang mở cho cộng đồng đóng góp, hoặc mở một PR độc lập có kèm theo bằng chứng riêng. Các model mới cũng có thể được thêm bằng một PR độc lập, xem Thêm một model mới. Nhân viên Hugging Face, người duy trì và một số người đóng góp lâu năm được miễn các quy tắc này.

Khắc phục một vấn đề. Liên kết vấn đề với một từ khóa đóng như Fixes #123 trong mô tả PR. Bạn có thể làm việc trên:

• một vấn đề bạn đã mở, sau khi một người duy trì đã gắn nhãn triaged
• một vấn đề được gắn nhãn contributions-welcome
• một vấn đề được gắn nhãn New model, xem Thêm một mô hình mới

Các vấn đề của người khác không mở cho PR trừ khi một người duy trì đã nói rõ điều đó. Các PR liên kết đến một vấn đề mà bạn không thể xử lý sẽ bị đóng.

Bạn không cần xin phép trước khi làm việc với một issue đủ điều kiện, và chúng tôi không gán issue cho ai. Các bình luận kiểu “tôi có thể làm việc này không?” hay “hãy gán issue này cho tôi” chỉ gây nhiễu, vì vậy hãy bỏ qua chúng và mở PR của bạn. PR đầu tiên cho một issue sẽ được ưu tiên.

Trước khi làm việc trên một issue contributions-welcome hoặc New model, hãy kiểm tra xem ai đó đã mở PR cho nó chưa. Nếu có, đừng mở thêm PR khác. Nếu bạn phát hiện lỗi, hãy để lại các đề xuất trên PR hiện có. Chỉ mở một PR cạnh tranh nếu PR hiện có có lỗi cơ bản, hoặc đã cũ: tác giả của nó không phản hồi các bình luận đánh giá hoặc không đẩy thay đổi trong hai tuần. Một PR đang chờ đánh giá từ maintainer không được coi là cũ. Dù trong trường hợp nào, hãy giải thích lý do trong issue trước khi mở PR của bạn.

Các PR độc lập. Nếu chưa ai báo cáo vấn đề, bạn có thể mở một PR mà không cần issue. Các PR độc lập dành cho những thay đổi ngắn gọn nhưng có tác động thực sự, chẳng hạn như sửa lỗi, cải thiện hiệu suất, hoặc sửa một ví dụ bị hỏng trong tài liệu. Mô tả PR cần có cùng bằng chứng như một issue:

• cho một lỗi, một script ngắn bị lỗi trên main và chạy thành công với bản sửa của bạn, sử dụng một checkpoint đã công bố, một cấu hình mặc định, hoặc một quy trình làm việc được tài liệu hóa
• để cải thiện hiệu năng, các số liệu trước và sau trên một khối lượng công việc thực tế, chẳng hạn như một checkpoint đã công bố hoặc cấu hình mặc định, cùng với phần cứng bạn đã chạy. Một microbenchmark nhanh hơn của một hàm không nằm trên đường dẫn nóng (hot path) sẽ không được tính.

Nếu đã có một issue tồn tại cho vấn đề đó, PR của bạn sẽ được xử lý thông qua issue đó, bất kể bạn có liên kết đến nó hay không. Các PR độc lập sửa một issue hiện có, hoặc không kèm theo bằng chứng, sẽ bị đóng. Các yêu cầu này không áp dụng cho các model mới.

Thay đổi cần tạo issue trước. Các dọn dẹp mang tính cơ học không ảnh hưởng đến tính chính xác hoặc hiệu suất, và các sửa lỗi chính tả hoặc cách diễn đạt hàng loạt trong tài liệu, cần có issue trước khi tạo PR. Hãy đề xuất thay đổi, cách bạn sẽ thực hiện và số lượng tệp bị ảnh hưởng. Việc sửa một lỗi chính tả duy nhất là quá nhỏ để tạo PR theo bất kỳ con đường nào.

Đánh giá PR của người khác. Các đánh giá từ cộng đồng được hoan nghênh khi chúng mang đến cho chúng tôi thông tin mới, nhưng các maintainer sẽ đọc mọi bình luận trên một PR và chúng tôi đã có sẵn các công cụ đánh giá của riêng mình. Trước khi bạn bình luận trên một PR mà bạn không mở, hãy đảm bảo rằng bạn có điều cụ thể để nói:

• Nếu bạn phát hiện một vấn đề hoặc có một thay đổi cụ thể để đề xuất, hãy để lại một bình luận inline trên các dòng liên quan, lý tưởng nhất là dưới dạng một đề xuất GitHub mà tác giả có thể áp dụng trực tiếp. Một đoạn mã tái hiện lỗi sẽ hữu ích nếu bạn đang báo cáo một bug.
• Nếu bạn đã báo cáo vấn đề mà PR này khắc phục, một ghi chú ngắn cho biết liệu nó có giải quyết được trường hợp của bạn không sẽ thực sự hữu ích.
• Vui lòng không đăng các bản tóm tắt chung chung hoặc các báo cáo kiểu “Tôi đã kiểm tra và nó hoạt động”. Việc phê duyệt từ những người không phải maintainer không ảnh hưởng đến việc một PR có được merge hay không, và một bình luận dài lặp lại nội dung của PR chỉ làm tốn thời gian của chúng ta mà không thay đổi kết quả.

Cách bạn viết code là do bạn quyết định, nhưng bạn chịu trách nhiệm cho mọi thứ bạn gửi lên, và chúng tôi có thể chặn các tài khoản liên tục mở các issue hoặc PR chất lượng thấp. Vui lòng cũng tôn trọng mã ứng xử của chúng tôi.

Cài đặt

1. Fork Transformers bằng nút Fork trên GitHub để có một bản sao dưới tài khoản của bạn, sau đó clone về máy cục bộ.

   Đã sao chép

   git clone git@github.com:<your Github handle>/transformers.git
   cd transformers

2. Thêm kho Transformers dưới dạng remote có tên upstream. origin trỏ đến fork của bạn và upstream trỏ đến nguồn sự thật. Điều này cho phép bạn đồng bộ main cục bộ trước khi đẩy lên origin và mở một PR.

   Đã sao chép

   git remote add upstream https://github.com/huggingface/transformers.git
   git remote -v
   # origin    git@github.com:<your Github handle>/transformers.git (fetch)
   # origin    git@github.com:<your Github handle>/transformers.git (push)
   # upstream  https://github.com/huggingface/transformers.git (fetch)
   # upstream  https://github.com/huggingface/transformers.git (push)

3. Giữ cho fork của bạn luôn cập nhật và tạo một nhánh để bắt đầu làm việc. Bạn cũng có thể đồng bộ hóa fork từ giao diện GitHub bằng nút Sync fork.

   Đã sao chép

   git checkout main && git pull upstream main && git push origin main
   git switch -c a-descriptive-name-for-my-branch

4. Cài đặt thư viện ở chế độ có thể chỉnh sửa. Sử dụng [dev] cho hầu hết các đóng góp vì nó bao gồm các công cụ phát triển cần thiết cho các kiểm tra về phong cách và chất lượng. Sử dụng [torch,testing] cho các đóng góp về mô hình, hoặc [quality] cho các thay đổi chỉ liên quan đến tài liệu và các sửa lỗi nhỏ khi không cần bộ phụ thuộc phát triển đầy đủ.

   Đã sao chép

   pip install -e ".[dev]"
   
   # for model contributions
   pip install -e ".[torch,testing]"
   
   # for docs-only changes and small fixes
   pip install -e ".[quality]"

Windows

Trên Windows, trừ khi bạn đang sử dụng WSL, hãy cấu hình git để chuyển đổi kết thúc dòng CRLF sang LF.

git config core.autocrlf input

Một cách để chạy lệnh make trên Windows là sử dụng MSYS2.

1. Tải xuống MSYS2 (chúng tôi giả định nó được cài đặt tại C:\msys64).
2. Mở dòng lệnh C:\msys64\msys2.exe (nó nên có sẵn từ menu Bắt đầu).
3. Chạy trong shell: pacman -Syu và cài đặt make bằng pacman -S make.
4. Thêm C:\msys64\usr\bin vào biến môi trường PATH của bạn.

Bạn giờ có thể sử dụng make từ bất kỳ terminal nào (PowerShell, cmd.exe, v.v.).

Mở các vấn đề

Sử dụng các mẫu issue và đảm bảo rằng issue chưa được báo cáo trước đó (dùng thanh tìm kiếm trên GitHub ở mục Issues). Báo cáo lỗi phải liên quan đến một lỗi trong Transformers, không phải trong mã của bạn, và phải ảnh hưởng đến việc sử dụng thực tế cũng như các checkpoint thực tế; một “lỗi lý thuyết” được phát hiện bằng cách đọc mã và cần một cấu hình rất không chuẩn để kích hoạt sẽ không được phân loại trừ khi đó là vấn đề bảo mật. Bao gồm một script ngắn, tự chứa để tái hiện lỗi trên bản phát hành mới nhất hoặc main, sử dụng một checkpoint đã công bố hoặc cấu hình mặc định. Các báo cáo lỗi không có trình tái hiện có thể chạy được sẽ không được phân loại.

Nếu bạn không chắc lỗi nằm ở mã của bạn hay ở thư viện, hãy hỏi trước trên diễn đàn hoặc Discord. Điều này giúp GitHub tập trung vào các vấn đề thư viện có thể xử lý được.

Thêm một mô hình mới

Việc thêm một mô hình vào Transformers giúp bất kỳ ai cũng có thể tải, tinh chỉnh hoặc chạy suy luận cho mô hình đó. Trước khi bắt đầu triển khai, hãy xác định các điểm khác biệt giữa kiến trúc của bạn và các mô hình tiên tiến gần đây đã có trong Transformers. Giải thích những điểm khác biệt đó trong issue hoặc PR để các reviewer có thể nhanh chóng hiểu được những thách thức mà mô hình mang lại, những phần nào có thể tái sử dụng các mẫu có sẵn, và những gì nên được chuẩn hóa giữa các mô hình.

Hãy làm theo các hướng dẫn bên dưới.

1. Thêm một model bằng modular Transformers — triển khai model bằng file modular và tạo ra các file modeling độc lập.
2. Tự động tạo docstring — sử dụng decorator @auto_docstring để tạo các docstring nhất quán mà không cần boilerplate.
3. Thử nghiệm — viết và chạy các bài kiểm tra mô hình để xác minh tính chính xác và giữ cho đóng góp có thể bảo trì được. Đối với mô hình ngôn ngữ nhân quả, hãy kế thừa từ bộ kiểm tra LM nhân quả khi có thể. Ưu tiên các bài kiểm tra tích hợp vì chúng xác minh toàn bộ đường dẫn của bộ xử lý, bộ phân từ và mô hình đối với các checkpoint thực tế.
4. Quy tắc cấu trúc mô hình — kiểm tra xem các tệp của bạn có vượt qua các quy tắc cấu trúc mô hình tĩnh được thực thi bởi make typing hay không.

Một số phần bổ sung cho mô hình cần thêm công tác tích hợp.

• Thêm các thành phần xử lý thị giác nếu mô hình của bạn yêu cầu đầu vào hình ảnh hoặc video.
• Tải trọng số động nếu tên tham số của checkpoint đã phát hành không khớp với cài đặt Transformers.

Lộ trình thêm mô hình

Có bốn mốc thời gian cho việc thêm mô hình, tùy thuộc vào người đóng góp mô hình và nhu cầu của cộng đồng đối với một kiến trúc.

• Tích hợp ngay từ ngày đầu tiên: đưa mô hình vào Transformers ngay trong ngày phát hành với một bản phát hành phiên bản mới. Chúng tôi cung cấp hỗ trợ cho các tính năng cốt lõi quan trọng nhất (lượng tử hóa, FlashAttention, KV-cache, v.v.), xem xét các bản nháp ban đầu và cũng có thể đảm nhận việc triển khai mô hình tùy thuộc vào tiến độ.

  Gửi email đến transformers@huggingface.co trước vài tuần, đặc biệt là với các kiến trúc mới. Chúng tôi sẽ phối hợp với bạn trên một nhánh riêng tư cho đến khi checkpoint và bản phát hành của bạn sẵn sàng.

• Tích hợp trong cùng tuần: các model có nhu cầu cao thường được đưa vào trong vòng một tuần, ngay cả khi tác giả không chủ động liên hệ.

  Mở một issue với mẫu mô hình mới để yêu cầu. Các issue có nhiều hoạt động hơn sẽ được ưu tiên xử lý nhanh hơn.

• Tích hợp sau khi phát hành: các mô hình không có nhu cầu mạnh, hoặc mà chúng tôi không có đủ nguồn lực để tiếp nhận, sẽ được đưa vào sau khi phát hành upstream.

  Người đóng góp bên ngoài có thể mở một PR cho một model mới trực tiếp, có hoặc không kèm theo issue. Trước khi bắt đầu, hãy kiểm tra các issue “New model” đang mở và các PR đang mở để đảm bảo rằng chưa ai đang thêm model đó. Chúng tôi sẽ xem xét và hướng dẫn bạn qua quy trình.

• Phát hành ưu tiên Hub: phát hành mô hình của bạn trực tiếp trên Hub thông qua hỗ trợ remote-code của Transformers, không cần PR upstream.

  Các mô hình Hub-first phổ biến thường được tích hợp vào Transformers sau đó, qua đó mở khóa tài liệu, bảo trì và tối ưu hóa ở cấp độ cao nhất. Hub-first là cách ít ma sát nhất để thêm một mô hình. Tuy nhiên, nó có thể kém ổn định hơn nếu mô hình yêu cầu chuyển đổi trọng số hoặc gặp các vấn đề tương thích ngược khác.

Tài liệu

Đối với tham chiếu API được tạo từ các tệp nguồn, hãy sử dụng bộ trang trí @auto_docstring khi phù hợp. Xem README của tài liệu để biết thêm chi tiết về cách chỉnh sửa tài liệu và cú pháp mà chúng tôi sử dụng.