貢獻 🤗 Transformers

我們歡迎所有人做出貢獻，並珍視每個人的貢獻。程式碼貢獻並不是幫助社群的唯一方式。回答問題、幫助他人和改進文件也具有巨大的價值。

如果您能口口相傳，也會對我們有所幫助！在關於其實現的精彩專案的部落格文章中引用該庫，在 Twitter 上每次它幫助到您時都大聲宣傳，或者僅僅給倉庫加星以示感謝。

無論您選擇如何貢獻，請注意並遵守我們的行為準則。

本指南深受出色的scikit-learn 貢獻指南的啟發。

貢獻方式

有幾種方式可以為 🤗 Transformers 做出貢獻

• 修復現有程式碼中的突出問題。
• 提交與錯誤或所需新功能相關的問題。
• 實現新模型。
• 為示例或文件做出貢獻。

如果您不知道從何開始，有一個特殊的首個良好問題列表。它會為您提供一份對初學者友好的開放問題列表，幫助您開始為開源做貢獻。最好的方法是開啟一個拉取請求並將其連結到您想要處理的問題。我們儘量優先處理已開啟的拉取請求，因為我們可以輕鬆跟蹤修復進度，如果貢獻者沒有時間，其他人可以接手拉取請求。

對於稍微更具挑戰性的任務，您也可以檢視第二個良好問題列表。但總的來說，如果您覺得您知道自己在做什麼，儘管去做，我們會幫助您實現目標！🚀

所有貢獻對社群都同樣有價值。🥰

修復未決問題

如果您發現現有程式碼存在問題並已有修復方案，請隨時開始貢獻並開啟一個拉取請求！

提交與錯誤相關的問題或功能請求

提交與錯誤相關的問題或功能請求時，請儘量遵循以下準則。這將使我們能夠更快地回覆您並提供良好的反饋。

您發現錯誤了嗎？

🤗 Transformers 庫之所以健壯可靠，歸功於使用者報告他們遇到的問題。

在您報告問題之前，如果您能**確保該錯誤尚未被報告**（使用 GitHub 上“問題”下的搜尋欄），我們將不勝感激。您的問題也應與庫本身的錯誤相關，而非您的程式碼。如果您不確定錯誤是在您的程式碼中還是在庫中，請先在論壇或我們的Discord上提問。這有助於我們更快地解決與庫相關的錯誤，而不是一般性問題。

一旦您確認該錯誤尚未被報告，請在您的問題中包含以下資訊，以便我們快速解決：

• 您的**作業系統型別和版本**以及**Python**、**PyTorch**和**TensorFlow**（如適用）的版本。
• 一個簡短、自包含的程式碼片段，使我們能夠在30秒內重現該錯誤。
• 如果引發了異常，請提供*完整的*回溯資訊。
• 附上您認為可能有幫助的任何其他資訊，例如截圖。

要自動獲取作業系統和軟體版本，請執行以下命令

transformers env

您也可以從倉庫根目錄執行相同的命令

python src/transformers/commands/transformers_cli.py env

您想要一個新功能嗎？

如果您希望在 🤗 Transformers 中看到新功能，請開啟一個問題並描述

1. 此功能背後的*動機*是什麼？它是否與庫中的問題或挫敗感相關？它是否是您專案所需的功能？它是否是您研究過並認為可能對社群有益的功能？

   無論是什麼，我們都樂意聽到！

2. 儘可能詳細地描述您請求的功能。您提供的資訊越多，我們就能更好地幫助您。

3. 提供一個*程式碼片段*來演示該功能的使用。

4. 如果該功能與某篇論文相關，請附上鍊接。

如果您的議題寫得好，那麼在您建立它的時候，我們已經完成了80%的工作。

我們添加了模板來幫助您開始您的問題。

您想實現新模型嗎？

新模型不斷髮布，如果您想實現一個新模型，請提供以下資訊：

• 模型的簡短描述和論文連結。
• 如果實現是開源的，請提供連結。
• 如果模型權重可用，請提供連結。

如果您願意自己貢獻模型，請告訴我們，以便我們幫助您將其新增到 🤗 Transformers！

我們有一份關於如何將模型新增到 🤗 Transformers 的技術指南。

您想新增文件嗎？

我們一直在尋找改進文件的方法，使其更加清晰和準確。請告訴我們如何改進文件，例如錯別字以及任何缺失、不清楚或不準確的內容。我們很樂意進行更改，如果您有興趣，我們將幫助您做出貢獻！

有關如何生成、構建和編寫文件的更多詳細資訊，請檢視文件 README。

建立拉取請求

在編寫任何程式碼之前，我們強烈建議您搜尋現有的拉取請求或問題，以確保沒有人已經在處理相同的事情。如果您不確定，最好開一個問題以獲得一些反饋。

您需要基本的 `git` 熟練度才能為 🤗 Transformers 做出貢獻。雖然 `git` 不是最容易使用的工具，但它擁有最棒的手冊。在 shell 中輸入 `git --help` 即可享受！如果您更喜歡書籍，Pro Git 是一個非常好的參考。

您需要 **Python 3.9** 或更高版本才能為 🤗 Transformers 做出貢獻。按照以下步驟開始貢獻：

1. 透過點選倉庫頁面上的**Fork**按鈕來派生倉庫。這會在您的 GitHub 使用者賬號下建立一個程式碼副本。

2. 將您的 fork 克隆到本地磁碟，並將基礎倉庫新增為遠端倉庫。

   已複製

   git clone git@github.com:<your Github handle>/transformers.git
   cd transformers
   git remote add upstream https://github.com/huggingface/transformers.git

3. 建立一個新分支來存放您的開發更改。

   已複製

   git checkout -b a-descriptive-name-for-my-changes

   🚨 **不要**在 `main` 分支上工作！

4. 在虛擬環境中執行以下命令以設定開發環境

   已複製

   pip install -e ".[dev]"

   如果虛擬環境中已經安裝了 🤗 Transformers，請使用 `pip uninstall transformers` 將其刪除，然後使用 `-e` 標誌以可編輯模式重新安裝。

   根據您的作業系統，並且由於 Transformers 的可選依賴項數量不斷增長，您可能會在使用此命令時遇到失敗。如果發生這種情況，請確保安裝您正在使用的深度學習框架（PyTorch、TensorFlow 和/或 Flax），然後執行：

   已複製

   pip install -e ".[quality]"

   這對於大多數用例來說應該足夠了。

5. 在您的分支中開發功能。

   在您編寫程式碼時，應確保測試套件透過。像這樣執行受您更改影響的測試：

   已複製

   pytest tests/<TEST_TO_RUN>.py

   有關測試的更多資訊，請檢視測試指南。

   🤗 Transformers 依靠 `black` 和 `ruff` 來統一格式化其原始碼。進行更改後，請使用以下命令一次性應用自動樣式更正和無法自動化的程式碼驗證：

   已複製

   make fixup

   此目標也經過最佳化，僅適用於您正在處理的 PR 所修改的檔案。

   如果您更喜歡一個接一個地執行檢查，以下命令將應用樣式更正：

   已複製

   make style

   🤗 Transformers 還使用 `ruff` 和一些自定義指令碼來檢查編碼錯誤。質量控制由 CI 執行，但您可以使用以下命令執行相同的檢查：

   已複製

   make quality

   最後，我們有很多指令碼來確保在新增新模型時不會忘記更新某些檔案。您可以使用以下命令執行這些指令碼：

   已複製

   make repo-consistency

   要了解有關這些檢查以及如何解決其中任何問題的更多資訊，請檢視拉取請求檢查指南。

   如果您正在修改 `docs/source` 目錄下的文件，請確保文件仍然可以構建。此檢查也會在您開啟拉取請求時在 CI 中執行。要執行本地檢查，請確保您已安裝文件構建器。

   已複製

   pip install hf-doc-builder

   從倉庫根目錄執行以下命令

   已複製

   doc-builder build transformers docs/source/en --build_dir ~/tmp/test-build

   這將在 `~/tmp/test-build` 資料夾中構建文件，您可以使用您喜歡的編輯器檢查生成的 Markdown 檔案。您也可以在 GitHub 上開啟拉取請求時預覽文件。

   一旦您對更改滿意，使用 `git add` 新增已更改的檔案，並使用 `git commit` 在本地記錄您的更改

   已複製

   git add modified_file.py
   git commit

   請記住撰寫好的提交資訊，以清晰地傳達您所做的更改！

   為了使您的程式碼副本與原始倉庫保持同步，在您開啟拉取請求之前或在維護者要求時，請在 `upstream/branch` 上重新設定您的分支

   已複製

   git fetch upstream
   git rebase upstream/main

   將您的更改推送到您的分支

   已複製

   git push -u origin a-descriptive-name-for-my-changes

   如果您已經打開了一個拉取請求，您需要使用 `—force` 標誌進行強制推送。否則，如果拉取請求尚未開啟，您可以正常推送您的更改。

6. 現在您可以訪問您在 GitHub 上的倉庫派生，然後單擊**拉取請求**以開啟一個拉取請求。請確保您勾選了下面清單中的所有框。準備就緒後，您可以將更改傳送給專案維護者進行審查。

7. 維護者要求更改是正常的，我們的核心貢獻者也會遇到！為了讓所有人都能在拉取請求中看到更改，請在您的本地分支中工作並將更改推送到您的派生。它們將自動顯示在拉取請求中。

拉取請求清單

☐ 拉取請求標題應概括您的貢獻。
☐ 如果您的拉取請求解決了某個問題，請在拉取請求描述中提及問題編號，以確保它們已連結（並且檢視該問題的人知道您正在處理它）。
☐ 為了表明正在進行中的工作，請在標題前加上 `[WIP]`。這有助於避免重複工作，並將其與準備合併的 PR 區分開來。
☐ 確保現有測試透過。
☐ 如果新增新功能，也請新增相應的測試。

• 如果您要新增新模型，請確保使用 `ModelTester.all_model_classes = (MyModel, MyModelWithLMHead,...)` 以觸發通用測試。
• 如果您要新增新的 `@slow` 測試，請確保它們透過 `RUN_SLOW=1 python -m pytest tests/models/my_new_model/test_my_new_model.py`。
• 如果您要新增新的分詞器，請編寫測試並確保 `RUN_SLOW=1 python -m pytest tests/models/{your_model_name}/test_tokenization_{your_model_name}.py` 透過。
• CircleCI 不執行慢速測試，但 GitHub Actions 每晚都會執行！
  

☐ 所有公共方法都必須有資訊豐富的文件字串（例如，參見 `modeling_bert.py`）。
☐ 由於倉庫快速增長，請勿新增任何會顯著增加倉庫負擔的影像、影片和其他非文字檔案。相反，請使用 Hub 倉庫（例如 `hf-internal-testing`）來託管這些檔案，並透過 URL 引用它們。我們建議將與文件相關的影像放置在以下倉庫中：huggingface/documentation-images。您可以在此資料集倉庫上開啟 PR，並請求 Hugging Face 成員合併。

有關拉取請求上執行的檢查的更多資訊，請檢視我們的拉取請求檢查指南。

測試

包含一個廣泛的測試套件，用於測試庫行為和幾個示例。庫測試可以在 tests 資料夾中找到，示例測試可以在 examples 資料夾中找到。

我們喜歡 `pytest` 和 `pytest-xdist`，因為它速度更快。從倉庫根目錄，指定*子資料夾或測試檔案的路徑*來執行測試。

python -m pytest -n auto --dist=loadfile -s -v ./tests/models/my_new_model

同樣，對於 `examples` 目錄，指定*子資料夾或測試檔案的路徑*來執行測試。例如，以下命令測試 PyTorch `examples` 目錄中的文字分類子資料夾。

pip install -r examples/xxx/requirements.txt  # only needed the first time
python -m pytest -n auto --dist=loadfile -s -v ./examples/pytorch/text-classification

事實上，這正是我們 `make test` 和 `make test-examples` 命令的實現方式（不包括 `pip install`）！

您還可以指定一小組測試，以便只測試您正在處理的功能。

預設情況下，慢速測試會被跳過，但您可以將 `RUN_SLOW` 環境變數設定為 `yes` 來執行它們。這將下載許多千兆位元組的模型，因此請確保您有足夠的磁碟空間、良好的網際網路連線或足夠的耐心！

RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/models/my_new_model
RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./examples/pytorch/text-classification

與慢速測試類似，還有其他預設情況下在測試期間未啟用的環境變數：

• `RUN_CUSTOM_TOKENIZERS`: 啟用自定義分詞器的測試。

更多環境變數和附加資訊可在testing_utils.py中找到。

🤗 Transformers 只使用 `pytest` 作為測試執行器。它在測試套件本身中不使用任何 `pytest` 特定的功能。

這意味著 `unittest` 完全受支援。以下是使用 `unittest` 執行測試的方法：

python -m unittest discover -s tests -t . -v
python -m unittest discover -s examples -t examples -v

風格指南

對於文件字串，🤗 Transformers 遵循Google Python 風格指南。有關更多資訊，請檢視我們的文件編寫指南。

在 Windows 上開發

在 Windows 上（除非您在 適用於 Linux 的 Windows 子系統 或 WSL 中工作），您需要配置 git 將 Windows `CRLF` 行尾轉換為 Linux `LF` 行尾

git config core.autocrlf input

在 Windows 上執行 `make` 命令的一種方法是使用 MSYS2

1. 下載 MSYS2，我們假設它安裝在 `C:\msys64`。
2. 開啟命令列 `C:\msys64\msys2.exe` (它應該在**開始**選單中可用)。
3. 在 shell 中執行：`pacman -Syu` 並使用 `pacman -S make` 安裝 `make`。
4. 將 `C:\msys64\usr\bin` 新增到您的 PATH 環境變數中。

現在您可以在任何終端（PowerShell、cmd.exe 等）使用 `make` 了！🎉

將派生倉庫與上游主分支（Hugging Face 倉庫）同步

更新派生倉庫的主分支時，請遵循以下步驟，以避免 ping 上游倉庫，這會向上遊的每個 PR 新增引用註釋，並向參與這些 PR 的開發人員傳送不必要的通知。

1. 如果可能，避免使用派生倉庫上的分支和 PR 與上游同步。相反，直接合併到派生的主分支。

2. 如果 PR 是絕對必要的，請在檢出您的分支後按照以下步驟操作：

   已複製

   git checkout -b your-branch-for-syncing
   git pull --squash --no-commit upstream main
   git commit -m '<your message without GitHub references>'
   git push --set-upstream origin your-branch-for-syncing