PEFT documentation

PEFTへの貢献

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

PEFTへの貢献

PEFTへの貢献を歓迎します。貢献を予定されている方は、プロセスを円滑に進めるために、本ページをお読みください。

PRを開く前に議論し、承認を得てください

プルリクエスト(ドラフトを含む)を開く前に、huggingface/peft でイシューを開くか、既存のイシューを探し、提案する貢献について議論してください。既存のイシューがあり、すでに誰かが作業中である場合、作業する意向を表明している場合、またはオープンな PR がある場合は、別の PR を提出しないでください。PEFT のメンテナーまたは Hugging Face のメンバーが提案を明示的に承認するまでお待ちください。イシューを開く場合は、説明の長さや複雑さを、イシューの複雑さに比例させてください。多くの場合、長い説明よりも、再現手順を伴う短い説明の方が価値があります。

承認コメントにはメッセージ/peft-triage approvedが含まれます。割り当てられたコントリビューターの名前を併記することもでき、例えば/peft-triage approved usernameや/peft-triage approved @usernameのように指定します。割り当てられていないissueに対してPRを作成すると、そのPRはクローズされます。

PRの説明欄で、承認済みのオープンなissueを#123、huggingface/peft#123、またはhttps://github.com/huggingface/peft/issues/123の形式でリンクしてください。例外として、メンテナーは、個別の承認コメントなしに完全なGitHub URLで参照できる特定の長期にわたるディスカッションを指定できます。複数のissueやディスカッションを参照する場合、1つの有効な参照があれば十分です。

自動ワークフローにより、承認されたオープンな issue または discussion が PR に参照されているかチェックされます。有効な参照がない PR は、説明を添えて自動的にクローズされます。issue の承認を取得し、PR の説明を更新して、同じ PR を再オープンできます。代替の PR を作成しないでください。PR が誤ってクローズされたと思われる場合は、その PR でメンテナーに ping してください。

独立したstale botは、triagedラベルが付けられていても、非アクティブなアイテムをクローズし続ける場合があります。メンテイナーがあなたの貢献を見落としていると感じる場合は、彼らに通知(ping)を送ることができますが、2週間の非アクティブ期間が経過する前に送ることはできません。

インストール

貢献を始めるには、以下の手順に従ってください。

  1. リポジトリのページにある‘Fork’ボタンをクリックして、リポジトリをフォークします。これにより、GitHubユーザーアカウント配下にコードのコピーが作成されます。

  2. フォークをローカルディスクにクローンし、ベースリポジトリをリモートとして追加します。以下のコマンドは、公開SSH鍵がGitHubにアップロードされていることを前提としています。詳細については、こちらのガイドを参照してください。

    git clone git@github.com:<your Github handle>/peft.git
    cd peft
    git remote add upstream https://github.com/huggingface/peft.git
  3. 開発中の変更を保持するために新しいブランチを作成し、作業するすべての新しいPRに対してこれを行ってください。

    まず、mainブランチをupstream/mainブランチと同期してください(詳細はGitHub Docsを参照)。

    git checkout main
    git fetch upstream
    git merge upstream/main

    mainブランチが同期されたら、そこから新しいブランチを作成します:

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

    作業しないでください in the main branch.

  4. このライブラリでの作業用に作成した conda または仮想環境で、以下のコマンドを実行して開発環境を設定します:

    pip install -e ".[test]"

    (仮想環境にPEFTがすでにインストールされている場合は、再インストールする前にpip uninstall peftで削除してください。)

プルリクエストの作成が初めての場合は、GitHubのCreating a pull requestガイドに従ってください。

テストとコード品質チェック

貢献の種類にかかわらず(ドキュメントのみの場合を除く)、PRを作成する前にテストとコード品質チェックを実行し、貢献がプロジェクトの基準に準拠していること、および何らかの問題を引き起こさないことを確認する必要があります。

テストとチェックの実行

必要なテストを実行するためのMakefileを提供しています。ユニットテストを実行するには、以下のコードを実行してください。

make test

コードの品質とスタイルを確認するだけ、または確認して修正する場合は、以下のいずれかを実行します。

make quality  # just check
make style  # check and fix

make qualityを実行すると、PEFTの公開API(つまりpeft.__all__に記載されているすべてのもの)のすべてのメソッド/クラスがドキュメントに記載されているかもチェックされます。これらのエラーはmake styleでは修正できません。公開APIの新しい項目をドキュメントに記載して、このエラーを修正する必要があります。

また、pre-commitを設定して、Gitのコミットフックとしてこれらの修正を自動的に実行することもできます。

$ pip install pre-commit
$ pre-commit install

すべてのテストの実行には時間がかかることがあるため、開発中は、変更内容に関連するテストのみを実行する方が効率的な場合があります。例えば、以下のように実行できます:

pytest tests/<test-file-name> -k <name-of-test>

これにより、はるかに短時間で完了し、より高速な反復が可能になります。

テストの追加

新しいテストを追加する一般的なガイドについては、tests/README.mdを参照してください。

変更が特定のハードウェア設定(例: CUDA が必要)に特化している場合は、tests/test_gpu_examples.py と tests/test_common_gpu.py を確認し、そこにテストを追加するのが適切かどうかを検討してください。変更がモデルの保存と読み込みに影響を与える可能性がある場合は、--regression フラグを付けてテストを実行し、リグレッションテストをトリガーしてください。

古いPR

PRを作成している最中に、他の変更がマージされることでベースとなるコードベースが変更されることがあります。その場合、特にマージ競合が発生している場合は、最新の変更を反映してブランチを更新してください。マージでもリベースでも構いません。PRが準備完了したら、squash and mergeでマージします。レビューを容易にするため、force pushは避けてください。

PRの説明

PRを開く際は、提案する変更内容について適切な説明を記載し、上記の通り承認されたissueを参照してください。他のissueやPRに関連する場合は、それらも参照してください。良い説明を提供することは、レビュアーがより良く、より速くコードをレビューするのに役立つだけでなく、後でコミットメッセージの根拠としても使用でき、プロジェクトの長期的なメンテナンスに貢献します。

PRの説明の長さや複雑さは、変更内容に合わせてください。1行の些細な変更に対して、10段落もの説明は必要ありません。diffを見れば自明なことを繰り返さないでください(例:「'foobaar'のタイプミスを修正しました」)。

コードに非自明な変更を加えた場合は、その変更を説明するコメントをコードに追加することも有効です。例えば、最も自然な実装方法が機能せず、実装を複数回試行錯誤する必要があった場合、コードにコメントを追加すべきであることの明確な指標となります。

関連する場合は、変更内容のテスト方法を示してください。例えば、pytestのテストコマンドや再現コードを示すなどです。

レビュアーのフィードバック

PRを提出した後、通常、メンテナーが数日以内にフィードバックを返します。2週間以内にフィードバックが得られない場合は、メンテナーの目に留まらなかった可能性があります。その場合はメンテナーに連絡しても構いませんが、それより前に連絡しないでください。

レビュアーがインラインコメントを提供した場合、対応済みであっても解決済みとしてマークしないでください。これらのコメントは開いたままにしてください。レビュアーが作業を再開する際に役立ちます。

レビュアーからのフィードバックに対応した後、PRがレビュー可能な状態になったことをレビュアーに通知してください。

バグ修正

バグが発生した状況について説明してください。既存のissueがある場合は、リンクを貼ってください(例: “Resolves #12345”)。

理想的には、バグ修正が提供される場合、そのバグに対するテストが添付されるべきです。テストは現在のコードでは失敗し、バグ修正を適用したコードでは成功する必要があります。テストには、該当する issue または PR を参照するコメントを追加してください。テストがない場合、将来の回帰を防止することがより困難になります。

ドキュメントの改善

リンクの修正や、欠落・不明瞭なドキュメントの改善への貢献を歓迎します。また、この急速に変化する環境において、サンプルが最新かつ正常に動作することを確認し、メンテナンスを行うことも、非常に高く評価されます。

タイポの修正のみを含むプルリクエストを送信しないでください。これらの変更は、一般的に節約する作業量よりも多くの作業を生み出します。このような変更は、より実質的な修正(壊れたリンクの修正や、ドキュメントの拡張/更新など)と組み合わせて行う方が適切です。

新しいPEFTファインチューニング手法を追加

新しいパラメータ効率の良いファインチューニング手法は常に開発されています。PEFTに新しい有望な手法を追加したい場合は、以下の手順に従ってください。

  1. 元の論文の著者でない場合、既存の実装を確認し、著者自身がPRを提出する予定がないことを必ず確認してください。
  2. 上記に記載されているように、明示的な承認を得るまで、以下のコア統合作業を開始しないでください。承認を得る前に、提案のIssueを開いてください。
  3. 新しいPEFTメソッドが追加されていないか、インスピレーションを得るために最近のコミットを確認してください。
  4. 提案が承認された後、方法が基本的に動作し、最初のテストがパスした時点で、早めにドラフトPRを開き、フィードバックを依頼すると有用です。ドラフトPRの説明欄で、承認されたissueを参照してください。

新しいPEFT手法のコア統合

  • 作業に多くの時間を費やす前に、huggingface/peft に issue を作成し、明示的な承認を得てください。
  • メソッドの出典をリンクします。通常は最終論文または、その他の安定した一次情報源です。実装が安定している必要があるため、まだ査読中の研究は避けることを目指しています。
  • src/peft/utils/peft_types.py に新しい PeftType エントリを追加します。
  • src/peft/tuners/ の下に、メソッドに必要なファイル(通常は config.py、model.py、layer.py、__init__.py)を含む新しいチューナーパッケージを作成します。
  • チューナーの__init__.pyにregister_peft_method(...)でメソッドを登録します。
  • 新しい設定/モデルをsrc/peft/tuners/__init__.pyおよびsrc/peft/__init__.pyからエクスポートします。
  • Transformersモデルのデフォルトのターゲットモジュールが必要なメソッドの場合、src/peft/utils/constants.pyにマッピングを追加してください。
  • 最も広範かつ迅速なテストであるため、tests/test_custom_models.py のテストマトリクスにメソッドを追加します。pytest tests/test_custom_models.py -k <method-name> -v でテストがパスすることを確認し、失敗があれば修正してください。
  • プッシュする前に、make style を実行してスタイル/品質チェックを行ってください。
  • PRの説明欄で、手法を説明し、論文へのリンクを貼り付け、トレードオフを要約し、追加した内容を列挙してください。

新しいPEFTメソッドを追加するための完全なPR

  • メソッド固有の設定引数が適切に命名され、説明されていることを確認してください。ユーザーが論文の内容を完全に把握しているとは仮定しないでください。
  • PEFTの命名規則とコーディング規約に従ってください。
  • 意図せず関連のない変更(コードフォーマッタが関連のないファイルを変更した、など)をコミットしていないことを確認してください。
  • 実装の選択が自明でない場合は、コードのコメントで文書化してください。
  • テストマトリクスに PEFT メソッドを追加して、完全なテストスイート(test_config.py、test_decoder_models.py など)を完成させてください。テストがパスすることを確認してください。
  • docs/source/package_reference/ に、短い説明、論文へのリンク、使用例のスニペット、autodoc ブロックを含むドキュメントを追加します。LoRA などの他の手法と比較した際の長所と短所を説明します。そのドキュメントページを docs/source/_toctree.yml に登録します。
  • examples/ 配下に実行可能な例を追加してください(既存の例のコピーでも構いません)。短いREADME.mdも用意してください。
  • Check the benchmarks in method_comparison/ and add experiment settings for your new method. This is a good place to sanity check that the PEFT method trains as expected. Include one or two reasonable benchmark configurations (one default, one optimized for the benchmark).
  • 推奨: 汎用的な量子化サポートを追加します。各量子化手法に対して量子化レイヤーの型を明示的に追加する代わりに、汎用的な量子化をサポートしてください。実装の例として、BOFTのコードを確認してください。https://github.com/huggingface/peft/blob/main/tests/test_quantization.pyにPEFT手法を追加して拡張してください。必要に応じて、メンテナーにサポートを依頼してください。

既存のPEFTメソッドの変更

PEFTメソッドに変更を加え、その出力が変更される可能性がある場合、つまり既に学習済みのチェックポイントが無効化される可能性がある場合は、追加の注意が必要です。詳細については、https://github.com/huggingface/peft/blob/main/.ai/skills/peft-method-changes/SKILL.md の説明を確認してください。そこの手順は、人間とAIの両方を対象としています。

その他の機能の追加

まず、上記で説明したように、新しい機能の追加を提案するIssueをGitHubに作成し、明示的な承認を待ちます。これにより、実装に多くの時間を費やす前に、その機能の追加が適切かどうかをメンテナーと検討できます。

新しい機能には、一般的にテストとドキュメントまたはサンプルを添える必要があります。これらがなければ、ユーザーがあなたの素晴らしい新機能を発見するのは困難になります。

コードの変更は、後方互換性を保つ形で実装する必要があります。例えば、機能のマージ後も、既存のコードが同じように動作し続ける必要があります。

Update on GitHub