# 🤗 Transformers に貢献する

> [!WARNING]
> Transformers リポジトリには現在、コードエージェントによって作成された大量の PR や issue コメントが殺到しており、レビューや対応のキャパシティがボトルネックになっています。そのため、現時点では**初回コントリビューターの方は、issue や PR の作成にコードエージェントを使用しないようお願いいたします**。また、自律エージェントについても、当面は PR や issue を開かないようお願いいたします。
>
> エージェントによって作成されたものと見なされるPRは、レビューなしでクローズされる可能性が高く、繰り返しまたは悪意を持って这种行为を行うユーザーはブロックされる場合があります。

 当社のコードエージェントの哲学の詳細

コードエージェントが極めて強力なツールであることは理解しています。Hugging Face においても、多くのメンバーが業務でこれを利用しています。しかし、**単にコードエージェントを実行してオープンソースプロジェクトに PR を生成した場合、あなたはレビュアーとエージェントの間の仲介者に過ぎない**という点に気づくことが重要です。この方法で生成された成果物は有用な貢献のように見えますが、実際にはあなたが関わる必要はありませんでした。レビュアー自身がコードエージェントを実行すれば済むことだからです。

エージェント時代において、オープンソースに有益な貢献をしたい場合は、**エージェントが単独ではできないことを実行する必要があります**。特に、以下は非常に役立ったと実感しています。
- バグの明確な診断。コードエージェントは、しばしばコードの肥大化を招くワークアラウンドで問題を素早く修正しようとする傾向があります
または、他のモデルとの互換性の問題です。問題の正確な原因を特定し、特にその問題が初めて現れたコミットを特定する（[git bisect](https://git-scm.com/docs/git-bisect) を使用する場合など）ことは、価値のある作業です。
- 差分を最小限に抑えてください。PRを確認し、不要な変更がないようにしてください。テストスクリプトをコミットしていないことを確認してください。
または無関係なファイルです。コメントは本当に必要な場合のみ追加してください。コードエージェントは、自分が行った膨大な作業に注意を引くために、3つの新しい関数や複数行にわたるコメントを追加したがる傾向があります。PRが1行の修正で済む場合は、1行の修正にしてください。これにより、PRのレビューがはるかに容易になり、承認される可能性が高まります。
- 問題を再現するために時間をかけてください。ユーザーが問題を報告した場合、その問題が実際に起因しているのは
ユーザーの環境に問題がある場合や、問題の診断を誤って無効な解決策を提案してしまう場合があります。多くのコードエージェントはユーザーのコメントを過信しがちで、不適切な解決策を導き出すことがあり、場合によっては存在しない問題に対してもそれが起こります。単純な再現スクリプトを作成して実行し、問題を確認することは価値があります。
- 他のモデルと比較します。Transformersのリポジトリは非常に大規模であり、多くのモデルが類似した処理を行っています。
バグを修正する際、そのバグが他のモデルにも存在するかどうかを確認することは価値があります。PRで「（他のモデル）と同じアプローチを使用して修正しました」と、関連するコードへのリンクを添えて記載されている場合、修正が正しく、コードベースの他の部分と互換性がある可能性が高いことを示すため、メンテナーにとって非常に役立ちます。コードエージェントはコードを「狭い範囲」でしか見ないことが多く、コードベースの他の部分とモデルが乖離する原因となる修正を行ってしまうことがあります。
- 小規模なPRや、いわゆる「雑務」的なPRは避けてください。以前はこうしたPRも受け入れていましたが、現在の大量のPRの状況では、それを受け入れることはできません。
コメント内の小さなスタイル変更やタイポ修正に時間を割く余裕があります。コードエージェントとは別に、何が本当に重要であるかを見極める良いセンスを持つこと自体が、価値を生み出します。コードエージェントは、コード解析によって発見される「理論上のバグ」に集中しがちですが、こうしたバグが実際に問題を引き起こすことはほとんどありません。攻撃者に悪用される可能性がある場合を除き、これらを修正する価値は通常ありません。
- ローカルおよびCIでテストを検証してください。PRを開く前に、`make fix-repo`を実行し、`utils/tests_fetcher.py`を使用して
PRブランチで変更したファイルをカバーするテストの一覧を確認してください。それらのテストをローカルで実行し、PRを開く前にパスすることを確認してください。PRを開いた後は、CIがグリーンになっていることを確認し、レビューを依頼する前に問題があれば修正してください。これにより通知のスパムが大幅に減り、メンテナーの負担を軽減できます。

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

どこから手をつけていいか分からない場合は、初心者向けの課題として[Good First Issues](https://github.com/huggingface/transformers/labels/Good%20First%20Issue)をご覧ください。より挑戦的な課題を探している場合は、[Good Second Issues](https://github.com/huggingface/transformers/labels/Good%20Second%20Issue)を確認してください。貢献の形を問わず、[行動規範](https://github.com/huggingface/transformers/blob/main/CODE_OF_CONDUCT.md)を尊重し、他者への配慮を忘れないでください。

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

このガイドは、[scikit-learnのコントリビューティングガイド](https://github.com/scikit-learn/scikit-learn/blob/main/CONTRIBUTING.md)に大きく影響を受けています。

## 目次

1. [セットアップ](#set-up)
   - [Windows](#windows)
2. [Issueの作成](#opening-issues)
   - [バグ関連の問題](#bug-related-issue)
   - [機能リクエスト](#feature-request)
3. [新しいモデルの追加](#adding-a-new-model)
   - [モデル追加のタイムライン](#model-addition-timeline)
4. [ドキュメント](#docs)
5. [エージェントによる貢献](#agentic-contributions)

## セットアップ

1. GitHubの**Fork**ボタンを使用して[Transformers](https://github.com/huggingface/transformers)をフォークし、自分のアカウント配下にコピーを作成してから、ローカルにクローンしてください。

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

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

  ```bash
  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** ボタンを使ってフォークを同期することもできます。

  ```bash
  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]`を使用してください。

  ```bash
  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](https://learn.microsoft.com/en-us/windows/wsl/) を使用していない場合、git を設定して `CRLF` の改行コードを `LF` に変換するようにしてください。

```bash
git config core.autocrlf input
```

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

1. [MSYS2 をダウンロード](https://www.msys2.org/)（`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の作成

[テンプレート](https://github.com/huggingface/transformers/tree/main/.github/ISSUE_TEMPLATE)を使って、はじめてください。

### バグ関連の問題

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

バグが自分のコードにあるのか、ライブラリにあるのか判断がつかない場合は、まず[フォーラム](https://discuss.huggingface.co/)または[Discord](https://discord.com/invite/hugging-face-879548962464493619)で質問してください。これにより、GitHubは対応可能なライブラリの問題に集中した状態を維持できます。

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

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

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

```bash
transformers env
```

### 機能リクエスト

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

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

## 新しいモデルの追加

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

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

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

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

- モデルが画像や動画の入力を必要とする場合は、[ビジョン処理コンポーネントを追加](https://github.com/huggingface/transformers/blob/main/docs/source/en/add_vision_processing_components.md)してください。
- 公開されたチェックポイントのパラメータ名が Transformers の実装と一致しない場合の、[動的な重みの読み込み](https://github.com/huggingface/transformers/blob/main/docs/source/en/weightconverter.md)。

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

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

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

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

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

  [new model template](https://github.com/huggingface/transformers/issues/new?assignees=&labels=New+model&projects=&template=new-model-addition.yml) を使用して Issue を作成し、リクエストしてください。アクティビティが多い Issue ほど、キューの優先順位が早く上がります。

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

  ["New model"](https://github.com/huggingface/transformers/issues?q=is%3Aopen+is%3Aissue+label%3A%22New+model%22)タグが付けられたオープンなissueは、外部のコントリビューターにとっての入口です。最も多くのリクエストがあるアーキテクチャから始めることで、インパクトを最大化できます。私たちはレビューを行い、進め方をご案内します。

- Hub 優先リリース: [remote-code](https://github.com/huggingface/transformers/blob/main/docs/source/en/models.md#custom-models) 対応により、Transformers を介してモデルを Hub に直接公開できます。アップストリームへの PR は不要です。

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

## ドキュメント

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

ドキュメントの編集方法や使用する構文の詳細については、[README](https://github.com/huggingface/transformers/blob/main/docs/README.md)を参照してください。

## エージェントによる貢献

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

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

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