拉取請求檢查

當你在 🤗 Transformers 上開啟一個拉取請求時，會執行大量的檢查，以確保你新增的補丁不會破壞任何現有功能。這些檢查分為四種類型：

• 常規測試
• 文件構建
• 程式碼和文件風格
• 通用倉庫一致性

本文件將嘗試解釋這些各種檢查是什麼以及它們背後的原因，以及如果其中一個檢查在你的 PR 上失敗，如何在本地除錯它們。

請注意，理想情況下，它們要求你在 Transformers 倉庫中進行開發安裝

pip install transformers[dev]

或可編輯安裝

pip install -e .[dev]

由於 Transformers 的可選依賴項數量已大幅增加，你可能無法全部獲取。如果開發安裝失敗，請務必安裝你正在使用的深度學習框架（PyTorch、TensorFlow 和/或 Flax），然後執行：

pip install transformers[quality]

或可編輯安裝

pip install -e .[quality]

測試

所有以 `ci/circleci: run_tests_` 開頭的作業都執行 Transformers 測試套件的一部分。每個作業都在特定環境中專注於庫的一部分：例如，`ci/circleci: run_tests_pipelines_tf` 在僅安裝 TensorFlow 的環境中執行管道測試。

請注意，為了避免在模組沒有實際更改時執行測試，每次只執行測試套件的一部分：會執行一個實用程式來確定 PR 前後庫中的差異（GitHub 在“檔案更改”選項卡中顯示的內容），並選擇受該差異影響的測試。該實用程式可以在本地從 Transformers 倉庫的根目錄執行，使用

python utils/tests_fetcher.py

該實用程式將

1. 檢查差異中的每個檔案，判斷更改是在程式碼中還是僅在註釋或文件字串中。只保留有實際程式碼更改的檔案。
2. 構建一個內部對映，為庫原始碼的每個檔案提供其遞迴影響的所有檔案。如果模組 B 匯入模組 A，則稱模組 A 影響模組 B。對於遞迴影響，我們需要一個從模組 A 到模組 B 的模組鏈，其中每個模組都匯入前一個模組。
3. 將此對映應用於步驟 1 中收集的檔案，從而獲得受 PR 影響的模型檔案列表。
4. 將每個檔案對映到其對應的測試檔案，並獲取要執行的測試列表。

在本地執行指令碼時，您應該會看到步驟 1、3 和 4 的結果打印出來，從而知道哪些測試正在執行。該指令碼還將建立一個名為 `test_list.txt` 的檔案，其中包含要執行的測試列表，您可以使用以下命令在本地執行它們：

python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_list.txt)

為了防止任何遺漏，完整的測試套件也會每天執行。

文件構建

`build_pr_documentation` 作業構建並生成文件預覽，以確保 PR 合併後一切正常。一個機器人將在你的 PR 中新增一個連結以預覽文件。你對 PR 所做的任何更改都會在預覽中自動更新。如果文件構建失敗，點選失敗作業旁邊的 Details 檢視問題所在。通常，錯誤就像 `toctree` 中缺少檔案一樣簡單。

如果你有興趣在本地構建或預覽文件，請檢視 docs 資料夾中的 README.md。

程式碼和文件風格

程式碼格式化應用於所有原始檔、示例和測試，使用 `black` 和 `ruff`。我們還有一個自定義工具負責文件字串和 `rst` 檔案的格式化（`utils/style_doc.py`），以及 Transformers `__init__.py` 檔案中執行的惰性匯入的順序（`utils/custom_init_isort.py`）。所有這些都可以透過執行以下命令啟動：

make style

CI 在 `ci/circleci: check_code_quality` 檢查中檢查這些是否已應用。它還會執行 `ruff`，它會對你的程式碼進行基本檢查，如果發現未定義或未使用的變數，它會發出警告。要在本地執行該檢查，請使用：

make quality

這可能需要很長時間，因此要僅對當前分支中修改過的檔案執行相同的操作，請執行：

make fixup

最後一條命令還將執行所有額外的倉庫一致性檢查。讓我們來看看它們。

倉庫一致性

這彙總了所有檢查，以確保你的 PR 使倉庫保持良好狀態，並由 `ci/circleci: check_repository_consistency` 檢查執行。你可以在本地透過執行以下命令來執行該檢查：

make repo-consistency

這會檢查：

• 所有新增到 init 的物件都已文件化（由 `utils/check_repo.py` 執行）
• 所有 `__init__.py` 檔案的兩個部分內容相同（由 `utils/check_inits.py` 執行）
• 所有從其他模組複製的程式碼與原始程式碼保持一致（由 `utils/check_copies.py` 執行）
• 所有配置類在它們的文件字串中至少有一個有效的檢查點（由 `utils/check_config_docstrings.py` 執行）
• 所有配置類只包含在相應的建模檔案中使用的屬性（由 `utils/check_config_attributes.py` 執行）
• README 的翻譯和文件的索引與主 README 具有相同的模型列表（由 `utils/check_copies.py` 執行）
• 文件中自動生成的表格是最新的（由 `utils/check_table.py` 執行）
• 即使未安裝所有可選依賴項，庫也具有所有可用物件（由 `utils/check_dummies.py` 執行）
• 所有文件字串都正確地文件了物件的簽名中的引數（由 `utils/check_docstrings.py` 執行）

如果此檢查失敗，前兩項需要手動修復，後四項可以透過執行命令為你自動修復：

make fix-copies

額外的檢查關注新增新模型的 PR，主要包括：

• 所有新增的模型都在自動對映中（由 `utils/check_repo.py` 執行）
• 所有模型都經過了適當的測試（由 `utils/check_repo.py` 執行）

檢查副本

由於 Transformers 庫在模型程式碼方面非常注重，每個模型都應該完全在一個檔案中實現，而不依賴於其他模型，因此我們添加了一種機制，可以檢查給定模型的層程式碼副本是否與原始程式碼保持一致。這樣，當出現 bug 修復時，我們可以檢視所有其他受影響的模型，並選擇是向下傳遞修改還是中斷副本。

此機制依賴於 `註釋` 形式的註釋。`xxx` 應包含下面要複製的類或函式的完整路徑。例如，`RobertaSelfOutput` 是 `BertSelfOutput` 類的直接副本，因此您可以在 此處 看到它有一個註釋：

# Copied from transformers.models.bert.modeling_bert.BertSelfOutput

請注意，您可以將其應用於相關的方法，而不是應用於整個類。例如，在 這裡，您可以看到 `RobertaPreTrainedModel._init_weights` 是如何從 `BertPreTrainedModel` 中相同的方法複製而來的，並帶有註釋：

# Copied from transformers.models.bert.modeling_bert.BertPreTrainedModel._init_weights

有時，除了名稱之外，副本完全相同：例如在 `RobertaAttention` 中，我們使用 `RobertaSelfAttention` 而不是 `BertSelfAttention`，但除此之外，程式碼完全相同。這就是 ` # Copied from` 支援使用以下語法進行簡單字串替換的原因：`Copied from xxx with foo->bar`。這意味著程式碼是複製的，其中 `foo` 的所有例項都替換為 `bar`。您可以在 此處 的 `RobertaAttention` 中看到它的使用方式，並帶有註釋：

# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert->Roberta

請注意，箭頭周圍不應有任何空格（除非該空格是要替換的模式的一部分）。

您可以新增多個用逗號分隔的模式。例如，在這裡 `CamemberForMaskedLM` 是 `RobertaForMaskedLM` 的直接副本，帶有兩個替換：`Roberta` 替換為 `Camembert`，`ROBERTA` 替換為 `CAMEMBERT`。您可以在 此處 看到這是透過註釋完成的：

# Copied from transformers.models.roberta.modeling_roberta.RobertaForMaskedLM with Roberta->Camembert, ROBERTA->CAMEMBERT

如果順序很重要（因為其中一個替換可能會與之前的替換衝突），則替換將從左到右執行。

另一種方法是當模式只是相同替換的不同大小寫（帶有大寫和小寫變體）時，只需新增選項 `all-casing`。在 此處 的 `MobileBertForSequenceClassification` 中有一個示例，註釋如下：

# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert->MobileBert all-casing

在這種情況下，程式碼是從 `BertForSequenceClassification` 複製而來，並替換了：

• `Bert` 替換為 `MobileBert`（例如在 init 中使用 `MobileBertModel` 時）
• `bert` 替換為 `mobilebert`（例如在定義 `self.mobilebert` 時）
• `BERT` 替換為 `MOBILEBERT`（在常量 `MOBILEBERT_INPUTS_DOCSTRING` 中）