Transformers documentation
プルリクエストのチェック
プルリクエストのチェック
プルリクエストを開くと、Hugging Face CI が複数のチェックを実行します。これらのチェックに合格する必要があります。
- CIの修正では、チェックをパスするためにローカルで実行するコマンドが記載されています。
- その後のセクションでは、コードの品質やリポジトリの一貫性など、各チェックが検証する内容について説明しています。
- テストでは、実行されるテスト、テストのカテゴリ、およびスローテストについて説明しています。
CIの修正
ほとんどの場合、make styleを実行するだけで、最もよくある失敗原因であるコード品質チェックをクリアできます。
make style
リポジトリの整合性、コピー、または自動生成ファイルに関する問題が発生した場合は、make fix-repo を実行してください。これにより、スタイル、コピー、ドキュメント文字列、自動生成ファイルが一度のパスで修正されます。
make fix-repo
より大規模な変更に対しては、以下の3コマンドのシーケンスがすべてのチェックを網羅します。負荷は大きくなりますが、pushする前にすべての問題を検出できます。
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 は、手動で修正する必要がある型エラーやモデル構造の違反を検出します。make check-repo は、最終的な読み取り専用パスを実行して、すべてが準備完了であることを確認できます。
CI はときどき不安定です。変更内容と無関係な項目でチェックが失敗した場合は、メンテナーに連絡して再実行を依頼してください。
コードの品質
コード品質チェックは、フォーマット、インポート、型チェック、モデル構造のルールをカバーします。make fix-repo および make typing に相当します。
make style(make fix-repo に含まれます)は、Ruff のリンティングとフォーマット、__init__.py のインポートの並び順、およびオートマッピングの一貫性を自動修正します。
make typing は ty を使用して型チェックを実行し、config クラスの命名規則や forward() シグネチャを含む TRansFormers (TRF) ルールを検証します。型エラーと TRF の違反は特定のルール番号が報告され、手動での修正が必要です。これらのルールは mlinter リポジトリに格納されています。すべての TRF ルールを確認するには python -m utils.mlinter --list-rules を、特定のルールの完全なドキュメントを表示するには python -m utils.mlinter --rule TRFXXX を実行してください。
TRFルールに例外が必要な場合は、以下のオプションのいずれかを選択してください(詳細は違反の抑制を参照)。
utils/mlinter/rules.tomlの該当するルールにおいて、allowlist_modelsリストにモデル名を追加してください。モデルファイル全体に例外を適用する場合は、この方法を使用します。# trf-ignore: TRFXXXを、対象の構文と同じ行、またはその直前の行に追加します。例外を1つの構文にのみ適用する場合に使用します。
リポジトリの整合性
リポジトリの整合性チェックはmake check-repoと同様ですが、最初の失敗で停止します。以下のカテゴリ間でリポジトリの内部整合性を保ちます。公開オブジェクトがインポート可能であること、コピーされたコードがソースと同期していること、自動生成ファイル(ダミー、ドキュメントテスト、メタデータ)がコードの現在の状態を反映していることです。新しいモデルについては、すべての新しいモデルクラスが自動マッピングに登録されていることも検証します。
| カテゴリ | 検証対象 | 自動修正されましたか? |
|---|---|---|
| Init ファイル | src/transformers/models/ 内の __init__.py ファイルは最新の状態です | make fix-repo |
| コピーとモジュール | # Copied from ブロックはソースと一致しており、モジュラー生成ファイルは最新の状態です | make fix-repo |
| Docstringとドキュメント | 引数のドキュメント文字列は、関数のシグネチャおよびドキュメントの目次と一致しています | make fix-repo |
| 自動生成ファイル | ダミー、パイプラインの型付け、doctest リスト、メタデータ、依存関係テーブル | make fix-repo |
| 設定の検証 | Config クラスには docstring に有効なチェックポイントが含まれており、config の属性はモデリングファイルと一致しています | マニュアル |
| レビュアーの割り当て | すべてのモデルディレクトリと、レビュアーファイル内のすべてのルールは、依然としてレビュアーに到達します | マニュアル |
レビュアーの割り当て
.github/scripts/codeowners_for_review_action は、どのファイルが誰によってレビューされるかを記録します。
所有権はファイルごとに解決され、より具体的なものから優先的に適用されます。
| どこ | 〜のように見えます | 使用用途 |
|---|---|---|
| モデルファイル | # Reviewers: @login を、modular_<model>.py または modeling_<model>.py の先頭のコメントブロックに記述します。 | そのモダリティのオーナー以外の人を必要とするモデルです。モジュラーコンバーターはヘッダーを生成されたモデリングファイルにコピーするため、タグは再生成後も保持されます。 |
| パスルール | .github/scripts/codeowners_for_review_action 内の /src/transformers/<area>/ @login | モデル以外のもの |
| モダリティのテーブル | @@modality/vision @login、同じファイル内 | docs/source/en/_toctree.yml のそのセクションにドキュメントページが配置されているすべてのモデル |
| キャッチオール | * @Rocketknight1 @ArthurZucker | 何もない |
新しいモデルにはどこにもエントリを追加する必要はありません。_toctree.yml にそのドキュメントページを追加するだけで、これはドキュメントの目次チェックで既に必須とされていることですが、それによりモデルが特定のモダリティに配置され、以降はモダリティのテーブルで自動的にカバーされます。
make check-repository-consistency は utils/check_reviewers.py を実行します。このスクリプトは、モデルがキャッチオール以外の誰にも割り当てられていない場合、ルールがどのファイルにもマッチしなくなった場合、またはモダリティのテーブルが目次と一致しない場合に失敗します。そのリゾルバーは transformers の依存関係ではありません。utils/checkers-requirements.txt にリストされており、チェッカーランナーは環境での初回実行時にこれをインストールします。インストールが実行できない場合(オフラインの場合など)、チェックはそれを報告して合格扱いにし、処理をブロックしません。
src/transformers/models の外側でオーナーが設定されていないパスは、注記として報告されます。リストするには:
python utils/check_reviewers.py --strict
テスト
CI は、PR で変更された内容に基づいて、対象となるテストのサブセットを実行します。CI は結合したテストを検出するために、pytest-random-order を使用してテストをわずかにランダムな順序で実行します。実行の開始時にランダムシードが出力されるため、--random-order-seed=<seed> を使用して同じ順序を再現できます。
テストがローカルの GPU では成功するものの CI では失敗する場合は、TRANSFORMERS_TEST_DEVICE="cpu" を設定して、CPU 上で失敗を再現できるか確認してください。
TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -v以下のセクションでは、テストの選択方法、実行されるジョブ、および低速なテストの対処法について説明します。
テストの選択
CI はすべての PR に対して完全なテストスイートを実行しません。CI はすべての PR で @slow で装飾されたテストをスキップし、PR がレビュー対象となった時点で、メンテナーが GPU 上でそれらをトリガーします。
utils/tests_fetcher.py は、変更されたファイルからインポート依存関係をトレースして影響を受けるテストを特定し、それらのテストのみを実行します。また、共有ユーティリティに変更を加えた際に、他のモデルでのリグレッションも検出します。フェッチャーは、変更されたファイルと影響を受けるテストを出力し、そのリストを tests_torch_test_list.txt に書き出します。
fetcherを使用して、CIが実行する内容を正確に再現します。
python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)
modeling_utils.pyやgeneration/utils.pyといったコアファイルを変更すると、影響を受けるサブセットだけでなく、すべてのモデルテストがトリガーされます。
モデルのすべてのテストを無条件で実行することもできます。直接実行はより高速なローカルでの健全性チェックですが、変更した共有コードによって他のモデルに生じたリグレッションを検出することはできません。
pytest tests/models/my_model/ -v
テストジョブのカテゴリ
テストは並列CIジョブに分割されており、各ジョブはパスパターンに基づいてファイルを選択します。モデルのPRに関連するジョブは以下の通りです。
tests_torch: モデリングのテスト(tests/models/*/test_modeling_*.py)tests_tokenization: トークナイザのテスト(tests/models/*/test_tokenization_*.py)tests_processors: プロセッサーおよびフィーチャーエクストラクターのテスト(tests/models/*/test_(processing|image_processing|feature_extractor)_*.py)tests_generate: 生成テストpipelines_torch: パイプラインのテストtests_training_ci: トレーニングループのテストtests_tensor_parallel_ci: テンソル並列テストtests_fsdp_ci: FSDP テスト
低速テスト
通常のCI実行では、@slowデコレータが付与されたテストはスキップされます。これらのテストは実際のチェックポイントのダウンロードや、大量の計算リソースを必要とするため、GPUインスタンス上で実行されます。また、PRがレビュー対象となった時点で、メンテナーによってトリガーされます。
Slow tests は NVIDIA A10 で実行され、数値結果は CI ハードウェアとローカルマシンの間でわずかに異なる場合があります。新しいモデルを追加する際、必要に応じてメンテナーは通常、テスト内のこれらの値を調整します。
以下のコマンドで、ローカル環境でスローテストを実行します。
RUN_SLOW=1 python -m pytest tests/models/my_model/ -v
ドキュメントのビルド
build_pr_documentation ジョブはドキュメントをビルドし、プレビューを生成します。ボットがPRにプレビューリンクを投稿し、マージ前にこのチェックがパスする必要があります。失敗の多くは、toctree へのエントリが欠けていることが原因です。ローカルでドキュメントをビルドする方法については、docs フォルダー内の README.md を参照してください。
# 構文からコピー
新しいモデルでは、
# Copied fromよりも モジュラーワークフロー(modular_*.py)を常に優先してください。# Copied fromは、可能な限り避けてください。
# Copied from メカニズムは、コピーされたコードをソースと同期させます。make fix-repo が実行されると、すべての # Copied from ブロックがチェックされ、オリジナルに合わせて更新されるため、# Copied from ブロック内の編集は上書きされます。代わりにソースを編集し、make fix-repo に変更を伝播させましょう。
# Copied fromの基本的な形式には、次のものがあります。
# 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-casingwith model->newModel 構文は、コピー後に文字列の置換を適用します。複数の置換はカンマで区切り、左から右の順に適用されます。all-casing オプションを使用すると、すべての大文字・小文字のバリアントが一度に置換されます(Bert、bert、BERT がそれぞれ MobileBert、mobilebert、MOBILEBERT に置き換わります)。