🤗 Transformers に貢献する

Transformers リポジトリは現在、コードエージェントによって作成された大量の PR や issue コメントに押しつぶされかけています。これらをレビューし、対応する能力がボトルネックになっています。そのため、現時点では初回コントリビューターには、issue や PR の作成にコードエージェントを使用しないよう依頼しています。 また、自律エージェントにも、当面は PR や issue を開かないよう依頼しています。

エージェントによって作成されたものと見なされるPRは、レビューなしでクローズされる可能性が高く、繰り返しまたは悪意を持って这种行为を行うユーザーはブロックされる場合があります。

Transformers は、バグ修正、機能リクエストの提出、新モデルの実装、ドキュメントの改善など、すべての貢献を歓迎しています。

どこから始めればよいか分からない場合は、初心者向けの課題を探すためにGood First Issuesをご覧ください。より挑戦的な課題を探している場合は、Good Second Issuesを確認してください。貢献の形を問わず、行動規範を尊重し、他者への配慮を忘れないでください。

Transformers の使用が楽しかった場合は、ぜひ参照していただき、どのように活用しているかをお聞かせください。Twitter で言及していただくか、リポジトリにスターを付けていただければ幸いです。

このガイドは、scikit-learnのコントリビューティングガイドに大きく影響を受けています。

目次

1. セットアップ
   • Windows
2. Issue の作成
   • バグ関連の問題
   • 機能リクエスト
3. 新モデルの追加
   • モデル追加のタイムライン
4. ドキュメント
5. エージェントによる貢献

セットアップ

1. GitHubのForkボタンを使用してTransformersをフォークし、自分のアカウント配下にコピーを作成してから、ローカルにクローンしてください。

   コピーしました

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

2. upstream という名前で Transformers リポジトリをリモートとして追加します。origin はあなたのフォークを指し、upstream はソースの真実（source of truth）を指します。これにより、origin にプッシュして PR を作成する前に、ローカルの main を同期できます。

   コピーしました

   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. フォークを最新の状態に保ち、作業用のブランチを作成してください。GitHub の UI から Sync fork ボタンを使ってフォークを同期することもできます。

   コピーしました

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

4. ライブラリを編集可能モードでインストールします。スタイルや品質チェックに必要な開発ツールが含まれているため、ほとんどの貢献には[dev]を使用してください。モデルへの貢献には[torch,testing]を、完全な開発依存関係セットが不要なドキュメントのみの変更や小さな修正には[quality]を使用してください。

   コピーしました

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

Windows

Windows では、WSL を使用していない場合、git を設定して CRLF の改行コードを LF に変換するようにしてください。

git config core.autocrlf input

Windows で make コマンドを実行する方法の一つは、MSYS2 を使用することです。

1. MSYS2 をダウンロード（C:\msys64 にインストールされているものとします）。
2. コマンドライン C:\msys64\msys2.exe を開きます（スタート メニューから利用可能であるはずです）。
3. シェルで pacman -Syu を実行し、pacman -S make で make をインストールします。
4. PATH 環境変数に C:\msys64\usr\bin を追加してください。

これにより、make を任意のターミナル（PowerShell、cmd.exe など）から使用できるようになります。

Issueの作成

テンプレートを使って、はじめてください。

バグ関連の問題

Issue を作成する前に、そのバグがすでに報告されていないか確認してください（GitHub の Issues 内の検索バーを使用）。Issue は Transformers 側のバグである必要があり、ご自身のコードのバグではありません。

バグが自分のコードにあるのか、ライブラリにあるのか判断がつかない場合は、まずフォーラムまたはDiscordで質問してください。これにより、GitHubは実行可能なライブラリの問題に集中した状態を維持できます。

迅速に対応できるよう、以下の情報を含めてください。

• 該当する場合は、OSの種類とバージョン、Python、PyTorchのバージョン。
• バグを再現できる、短く自己完結したコードスニペット。
• 例外が発生した場合の完全なトレースバック。
• スクリーンショットなど、問題の解決に役立つと思われるその他の情報。

OSとソフトウェアのバージョンを自動的に取得するには、以下のコマンドを実行してください。

transformers env

機能リクエスト

Issue を作成し、以下を記述してください:

• ライブラリへの不満、プロジェクトの必要性、コミュニティに貢献できる可能性のある作業など、動機を記載してください。
• その機能について、可能な限り詳細に説明します。
• その機能の使用方法を示すコードスニペット。
• 該当する場合、関連する論文へのリンク。

新しいモデルの追加

Transformers にモデルを追加すると、誰でもそのモデルを読み込み、ファインチューニングや推論を実行できるようになります。実装を開始する前に、Transformers に既に存在する最新の最先端モデルと、ご自身のアーキテクチャの間の違いを特定してください。その違いを issue または PR で説明し、レビュアーがモデルがもたらす課題、既存のパターンを再利用できる部分、モデル間で標準化すべき部分を素早く理解できるようにしてください。

以下のガイドに従ってください。

1. モジュラー Transformers でモデルを追加する — モジュラーファイルを使用してモデルを実装し、独立したモデリングファイルを生成します。
2. ドキュメント文字列の自動生成 — @auto_docstring デコレーターを使用して、ボイラープレートなしで一貫性のあるドキュメント文字列を生成します。
3. テスト — モデルのテストを作成・実行し、正確性を検証するとともに、貢献が保守可能であることを保ちます。因果言語モデルの場合、可能な限り因果 LM テスターを継承してください。実際のチェックポイントに対して、プロセッサー、トークナイザー、モデルの全パスを検証できるため、統合テストを優先してください。
4. モデル構造のルール — make typing によって強制される静的なモデル構造のルールに、ファイルが準拠していることを確認してください。

一部のモデルの追加には、追加の統合作業が必要です。

• モデルが画像や動画の入力を必要とする場合は、ビジョン処理コンポーネントを追加してください。
• 公開されたチェックポイントのパラメータ名が Transformers の実装と一致しない場合の、動的な重みの読み込み。

モデル追加のタイムライン

モデルの追加には、モデルの貢献者やアーキテクチャに対するコミュニティの需要に応じて、4つのタイムラインがあります。

• Day-0統合: モデルのリリース日に、新しいバージョンのリリースを通じてTransformersで利用可能にします。最も重要なコア機能（量子化、FlashAttention、KV-cacheなど）のサポート、初期ドラフトのレビュー、およびスケジュールに応じてモデル実装の対応もお手伝いします。

  transformers@huggingface.co へ、特に新しいアーキテクチャの場合、数週間前にメールをお送りください。チェックポイントとリリースが準備できるまで、プライベートフォークで一緒に反復作業を行います。

• 同一週内への統合: 需要の高いモデルは、著者から連絡がなくても、通常1週間以内に統合されます。

  new model template を使用して Issue を作成し、リクエストしてください。アクティビティが多い Issue ほど、キューの優先順位が早く上がります。

• リリース後の統合: 需要が強くなく、または対応するリソースがないモデルは、アップストリームのリリース後に統合されます。

  “New model”タグが付けられたオープンなイシューは、外部のコントリビューターにとっての入口です。最も多くのリクエストがあるアーキテクチャから始めることで、インパクトを最大化できます。私たちはレビューを行い、進め方をご案内します。

• Hub 優先リリース:Transformers の remote-code 対応により、アップストリームへの PR を必要とせずに、モデルを直接 Hub に公開できます。

  Hub 中心のモデルは、後に Transformers に統合されることが多く、これにより一次対応のドキュメント、メンテナンス、最適化が利用可能になります。Hub 中心のアプローチは、モデルを追加する際の最も摩擦の少ない方法です。ただし、モデルが重みの変換やその他の後方互換性の問題に依存する場合、より脆弱になる可能性があります。

ドキュメント

ドキュメントの改善（誤字、内容の欠落、不明瞭な説明など）は常に歓迎されます。ソースファイルから生成されるAPIリファレンスについては、適用可能な場合は@auto_docstringデコレーターを使用してください。ドキュメントの重要な修正については、プルリクエストを直接開いてください。

ドキュメントの編集方法や使用する構文の詳細については、READMEを参照してください。

エージェントによる貢献

AI支援による貢献も歓迎します。レビュー負荷を管理可能な範囲に抑えるため、調整、スコープの明確化、検証が必要です。

• 「純粋なエージェント」によるPRの提出は行わないでください。人間の提出者は、変更されたすべての行のレビュー、エンドツーエンドでの動作検証、および関連するテストの実行に責任を負います。
• AI ツールを使用した場合は、PR の説明にその旨を明記し、調整リンク、既存の PR との差異（該当する場合）、およびテストのコマンドと結果を含めてください。
• 単発の「雑務」PR（単一のタイポ、孤立したスタイルの整理、1つのミュータブルなデフォルト値の修正など）は避けてください。機械的なクリーンアップは、明確で体系的なスコープにまとめてください。
• PRを開く前に問題点について調整し、類似のPRを確認して、承認を待ちます。

これらのトピックは、AGENTS.md に記載されており、エージェントが自律的に実装するための手順が指示されています。