Diffusers 🧨への貢献方法

AIエージェントを使用してコントリビュートする場合は、当社の期待とガイドラインを記載したAI支援およびエージェントによるコントリビュートセクションを必ずお読みください。

オープンソースコミュニティからの貢献を心から歓迎しています！どなたでも参加でき、コードに限らずあらゆる形の参加が重宝されています。質問への回答、他者へのサポート、コミュニティとのつながりづくり、ドキュメントの改善など、すべてがコミュニティにとって非常に価値のあるものです。ぜひ、意欲があれば遠慮なく参加してください！

まずは、私たちのパブリックなDiscordチャンネルで👋と挨拶することをお勧めします。拡散モデルの最新トレンドについて議論したり、質問をしたり、個人プロジェクトを披露したり、コントリビューションで互いに助け合ったり、ただリラックスして過ごしたりしています☕。

貢献の形を問わず、私たちはオープンで、歓迎の気持ちがあり、思いやりのあるコミュニティの一員であることを目指しています。行動規範をお読みいただき、やり取りの際にそれを尊重してください。また、私たちのプロジェクトを導く倫理ガイドラインにも精通し、同じ透明性と責任の原則に従っていただくことをお勧めします。

コミュニティからのフィードバックを非常に重視しています。ライブラリの改善に役立つと考えるフィードバックをお持ちの場合は、遠慮なくお声がけください。すべてのメッセージ、コメント、Issue、Pull Request (PR) は確認され、検討されます。

概要

issuesやdiscussionsでの質問への回答から、コアライブラリへの新しい拡散モデルの追加まで、さまざまな方法で貢献できます。

以下では、時間的コミットメントの少ない順に、貢献の異なる方法について概要を説明します。いずれの方法もコミュニティにとって価値のあるものです。

• 1. GitHub DiscussionsまたはDiscordで質問や回答を行うこと。
• 2. GitHub Issues タブで新しい問題を起票すること。
• 3. GitHubのIssuesタブで問題を回答します。
• 4. 「Good first issue」ラベルが付いたシンプルな問題を修正してください。詳細はこちらをご覧ください。
• 5. ドキュメントに貢献する。
• 6. Modular Diffusers を使用して、Hub にリモートコードとしてパイプラインまたはモデルを公開します。
• 7. examplesに貢献する。
• 8. 「Good second issue」ラベルが付いた、より難しい課題を修正してください。詳細はこちらを参照してください。
• 9. Diffusers MVPプログラムから課題を引き受けてください。
• 10. ライブラリに新しいパイプライン、モデル、またはスケジューラーを追加します。この貢献については、通常、モデルの著者の方々と直接連携して作業を進めます。コミュニティの貢献者の方は、代わりにHub（6）から始めてください。オープンな「New Pipeline/Model」および「New scheduler」のイシューを確認し、まずDesign Philosophyをお読みください。

前述したように、すべての貢献はコミュニティにとって価値のあるものです。 以下では、各貢献についてより詳しく説明します。

貢献4から10については、Hub上に存在する6を除き、PRを開く必要があります。その詳細な手順は、プルリクエストの作成で説明されています。

1. GitHub Discussions または Discord で質問・回答を行う

Diffusersライブラリに関するご質問やご意見は、GitHub DiscussionsまたはDiscordで受け付けています。対象となるご質問やご意見には、以下が含まれます（ただし、これらに限定されません）：

• 知識の共有を目的とした学習または推論実験の報告
• 個人プロジェクトの紹介
• 非公式なトレーニング例に関する質問
• プロジェクト提案
• 一般的なフィードバック
• 論文の概要
• Diffusers ライブラリを基盤として構築する個人プロジェクトに関するヘルプの依頼
• 一般的な質問
• 拡散モデルに関する倫理的な問題
• …

GitHub Discussions や Discord で質問されるすべての内容は、コミュニティが知識を公開して共有することを積極的に促し、将来同じ疑問を持つ初心者にとって非常に役立つ可能性があります。ためらわずに、気になる質問をどんどん投稿してください。 同じ精神で、こうした質問に答えることは、知識を公開して文書化し、すべての人が学べるようにするため、コミュニティにとって非常に大きな助けとなります。

ご留意ください。質問や回答に費やす努力が大きいほど、公開されている知識の品質は高くなります。同様に、適切に設定され、適切に回答された質問は、誰でもアクセスできる高品質な知識データベースを構築しますが、不適切な質問や回答は、公開知識データベース全体の品質を低下させます。 要するに、高品質な質問や回答は、正確で、簡潔で、関連性があり、理解しやすく、アクセスしやすく、適切に書式設定・設定されているものです。詳細については、良い issue の書き方セクションをご覧ください。

チャンネルに関する注意: GitHub Discussions は検索エンジンにインデックス付けされ、各スレッドにリンクを貼ることができるため、そこに投稿された質問と回答は、同じ問題を抱える次の人にも見つけやすくなります。 一方、Discord はチャットのような形式であり、素早いやり取りを促します。 Discord では質問への回答が得られるまでの時間は短くなる可能性が高いものの、時間が経つにつれて質問は見えなくなり、以前に投稿された情報を見つけるのははるかに困難です。そのため、長期的に残ることを目的とした質問と回答には GitHub Discussions の利用を推奨します。Discord での会話から興味深い結論が出た場合は、将来の読者が見つけられるよう、その結果をディスカッションとして投稿してください。

2. GitHubのissuesタブで新しいissueを開く

🧨 Diffusers ライブラリが堅牢で信頼できるものであるのは、問題に遭遇した際にその問題を報告してくださるユーザーのおかげです。問題を報告してくださったことに感謝いたします。

GitHub の issue は、Diffusers ライブラリに直接関連する技術的な質問、バグ報告、機能要望、またはライブラリ設計に関するフィードバックにのみ使用してください。

In a nutshell, this means that everything that is not related to the code of the Diffusers library (including the documentation) should not be asked as an issue, but rather on GitHub Discussions or Discord.

新しいissueを開く際は、以下のガイドラインをご検討ください：

• Issues の検索バーを使用して、GitHub で同様の質問が既に存在しないか確認してください。
• 別の（関連する）issueに新しいissueを報告しないでください。別のissueが強く関連している場合でも、新しいissueを開き、その関連issueへのリンクを貼ってください。
• 問題が英語で書かれていることを確認してください。
• 問題が最新の Diffusers バージョンへの更新によって解決される可能性があるか確認してください。問題を投稿する前に、python -c "import diffusers; print(diffusers.__version__)" の出力が最新の Diffusers バージョンと一致するかそれより新しいことを確認してください。
• 新しいIssueを開く際に費やす手間が大きいほど、得られる回答の質は高くなり、DiffusersのIssue全体の品質も向上します。

新しい問題には、通常、以下の内容が含まれます。

2.1. 再現可能で最小限のバグレポート

バグレポートには、再現可能なコードスニペットを必ず含め、できるだけ最小限かつ簡潔にしてください。 具体的には、以下のことを意味します。

• バグをできるだけ絞り込んでください。コードファイル全体をそのまま貼り付けるのは避けてください。
• コードを整形します。
• Diffusers に依存する外部ライブラリを除き、外部ライブラリを含めないでください。
• 常に、環境に関する必要な情報をすべて提供してください。そのために、シェルで diffusers-cli env を実行し、表示された情報をコピーして問題に貼り付けてください。
• 問題を説明してください。読者が問題の内容や、それが問題である理由を把握できていない場合、解決することはできません。
• 常に、読み手が最小限の手間で問題を再現できることを確認してください。コードスニペットが不足しているライブラリや未定義の変数のために実行できない場合、読み手はあなたを助けることができません。再現可能なコードスニペットは、できるだけ最小限に保ち、シンプルな Python シェルにコピー＆ペーストして実行できることを確認してください。
• 問題の再現にモデルおよび/またはデータセットが必要な場合は、読者がそのモデルやデータセットにアクセスできることを確認してください。モデルやデータセットをHubにアップロードすれば、簡単にダウンロードできるようになります。問題の再現をできるだけ容易にするため、モデルとデータセットはできるだけ小さく保ってください。

詳細については、良い issue の書き方セクションをご覧ください。

バグレポートはこちらから開くことができます。

2.2. 機能の要望

世界水準の機能リクエストは、以下の点に対応しています。

1. まず動機について:

• ライブラリに関する問題や不満に関連していますか？該当する場合は、その理由を説明してください。問題を再現するコードスニペットを提示するのが最善です。
• プロジェクトに必要な機能に関連していますか？ぜひお聞かせください！
• あなたが手がけており、コミュニティに役立つと考えるものですか? 素晴らしいですね! それがあなたにとってどのような問題を解決したのか教えてください。

2. その機能について説明する完全な段落を作成します。
3. 将来の使用方法を示すコードスニペットを提供します。
4. 論文に関連する場合は、リンクを添付してください。
5. 役立つと思われる追加情報（図面、スクリーンショットなど）を添付してください。

機能のリクエストはこちらから開くことができます。

2.3 フィードバック

ライブラリの設計に関するフィードバック、およびそれが良い/良くない理由についての情報は、コアメンテナーがユーザーフレンドリーなライブラリを構築する上で非常に役立ちます。現在の設計思想の背景にある哲学を理解するには、こちらをご覧ください。特定の設計判断が現在の設計思想と合致していないと感じる場合は、その理由と、どのように変更すべきかを説明してください。特定の設計判断が設計思想に厳密に従いすぎており、結果としてユースケースが制限されている場合は、その理由と、どのように変更すべきかを説明してください。 特定の設計判断が非常に有用であると感じる場合も、その旨をメモとして残してください。これは将来の設計判断にとって優れたフィードバックとなります。

フィードバックに関する問題をこちらで開くことができます。

2.4 技術的な質問

技術的な質問は、主にライブラリの特定のコードがなぜそのように書かれているのか、または特定のコード部分が何をしているのかに関するものです。該当するコードへのリンクを必ず記載し、そのコード部分がなぜ理解しにくいのかについて詳細を明記してください。

技術的な質問については、こちらでIssueを作成できます。

2.5 新しいモデル、スケジューラー、またはパイプラインの追加に関する提案

Diffusionモデルのコミュニティで、Diffusersライブラリに追加してほしい新しいモデル、パイプライン、またはスケジューラーがリリースされた場合は、以下の情報をご提供ください。

• 拡散パイプライン、モデル、またはスケジューラーの簡単な説明と、論文または公開リリースへのリンク。
• そのオープンソース実装へのリンク。
• 利用可能な場合、モデルの重みへのリンク。

また、コンポーネント（モデル、スケジューラ、パイプラインなど）の元の著者が特定できる場合は、GitHub ハンドルでタグ付けすることを忘れないでください。

モデルをDiffusersに追加したい場合は、Hubにパイプラインまたはモデルを公開するおよびパイプライン、モデル、スケジューラーの追加を参照してください。

モデル/パイプライン/スケジューラーのリクエストは、こちらから開くことができます。

3. GitHub の issues タブで問題を回答する

GitHub 上の issue への回答には、Diffusers に関するある程度の技術的な知識が必要になる場合がありますが、回答が 100% 正しいと確信が持てない場合でも、ぜひ挑戦してみてください。 issue に対して高品質な回答をするためのヒントをいくつかご紹介します。

• できるだけ簡潔かつ最小限にしてください。
• トピックに留まること。問題への回答は、その問題自体にのみ関わるべきです。
• 主張を裏付ける、または支持するコード、論文、その他のソースへのリンクを提示してください。
• コードで回答してください。問題の解決策が単純なコードスニペットで示せる場合、または問題の解決方法を示せる場合は、完全に再現可能なコードスニペットを提供してください。

また、多くの問題は単にオフトピックであったり、他の問題の重複であったり、関連性がなかったりします。そのような問題に対して回答し、問題の作成者により正確な記述を促したり、重複する問題へのリンクを提供したり、GitHub DiscussionsやDiscordへ誘導したりすることは、メンテナーにとって非常に大きな助けとなります。

発行されたバグレポートが正しく、ソースコードの修正が必要であると確認できた場合は、次のセクションをご覧ください。

6を除くすべての貢献には、PRを開く必要があります。プルリクエストを開くセクションで、その方法について説明しています。

4. 「Good first issue」の修正

Good first issuesには、Good first issueラベルが付けられています。通常、これらのissueには、修正を容易にするために、解決策の概要がすでに説明されています。 issueがクローズされておらず、修正を試みたい場合は、「I would like to try this issue.」というメッセージを残すだけで構いません。通常、以下の3つのシナリオがあります。

• a.) 問題の説明に修正方法がすでに提案されています。この場合、その解決策が妥当だと判断できる場合は、修正のための PR またはドラフト PR を作成できます。
• b.) 問題の説明に修正提案が含まれていない場合、その問題へのコメントで自分で修正を提案してください。アプローチを説明する数文で十分です。PR を作成する前に、Diffusers チームの誰かがそれを確認するのを待ってください。
• c.) すでにこの問題を修正するためのオープンなPRが存在するが、問題自体はまだクローズされていない場合。PRがstale（放置状態）になっている場合は、新しいPRをオープンして、そのstaleなPRへのリンクを貼るだけで構いません。元のコントリビューターが問題を修正しようとしていたものの、突然時間が取れなくなったために、PRがstaleになることはよくあります。これはオープンソースではよくあることで、ごく自然なことです。この場合、既存のPRの知見を活かして再挑戦してくれると、コミュニティは非常に喜ぶでしょう。すでにPRが存在し、かつアクティブな場合は、提案を行う、PRをレビューする、あるいはそのPRへの貢献を許可してもらえるか尋ねるなど、著者をサポートすることができます。

5. ドキュメントへの貢献

優れたライブラリは常に優れたドキュメントを備えています! 公式ドキュメントは、ライブラリの新規ユーザーにとって最初の接点の一つとなることが多く、そのためドキュメントへの貢献は非常に価値のある貢献です。

ライブラリへの貢献には、さまざまな形があります。

• スペルミスや文法エラーの修正。
• ドキュメント文字列の誤った書式を修正してください。公式ドキュメントの表示がおかしい場合や、リンクが壊れている場合、時間を割いて修正していただければ幸いです。
• docstringの入力または出力テンソルの形状や次元を修正します。
• 理解しにくい、または誤ったドキュメントを明確にします。
• 古いコードの例を更新します。
• ドキュメントを別の言語に翻訳する。

Diffusersの公式ドキュメントページに表示されている内容はすべて公式ドキュメントの一部であり、それぞれのドキュメントソースで修正や調整を行うことができます。

ドキュメントのローカルでの変更を検証する方法については、このページをご覧ください。

6. Hubにパイプラインまたはモデルを公開する

Modular Diffusersを使用すると、パイプラインをリモートコードとしてHubのリポジトリに配置できます。Diffusersのリリースを待たずに、from_pretrained(..., trust_remote_code=True)で誰でも読み込むことができます。新しいパイプラインやモデルをコミュニティに提供する貢献者の方は、ここから始めてください。パイプラインを公開するにはカスタムブロックを、モデルを公開するにはカスタムモデルを参照してください。

該当するモデルリクエスト（存在しない場合は新規作成してください）で教えてください。実装に関するフィードバックを提供し、気に入ったものはCommunity Modular Diffusers Blocksコレクションに紹介します。その後、ライブラリでのモデルサポート方法を決定します。あなたのバージョンをアップストリームに反映する、著者たちと公式バージョンについて協力する、あるいは単にあなたのバージョンを案内する、といった対応が考えられます。また、その過程で感じた摩擦点も教えてください。分かりにくいAPI、不足しているドキュメント、バグなどです。そのフィードバックは、パイプライン自体と同じくらい私たちにとって価値があります。

7. 学習例への貢献

Diffusersの例は、examplesに配置されているトレーニングスクリプトのコレクションです。

2種類の学習例に対応しています:

• 公式のトレーニング例
• 研究用の学習例

研究用の学習例は examples/research_projects に配置されており、公式の学習例は examples 配下のすべてのフォルダのうち、research_projects と community フォルダを除いたものです。 公式の学習例は Diffusers のコアメンテナーによって管理され、研究用の学習例はコミュニティによって管理されています。 これは、Diffusers ライブラリが Hub 上で公式パイプラインとコミュニティパイプラインの小さなセットのみを公開しているのと同じ理由です。拡散モデルのすべての可能な学習手法をコアメンテナーが維持することは現実的ではないためです。 Diffusers のコアメンテナーとコミュニティが、特定の学習パラダイムが実験的すぎる、または十分に普及していないと判断した場合、対応する学習コードは research_projects フォルダに配置し、著者が管理する必要があります。

公式のトレーニング例および研究例は、いずれも1つ以上のトレーニングスクリプト、requirements.txtファイル、README.mdファイルを含むディレクトリで構成されています。ユーザーがトレーニング例を利用するには、リポジトリをクローンする必要があります。

git clone https://github.com/huggingface/diffusers

また、トレーニングに必要なすべての追加の依存関係をインストールします:

cd diffusers
pip install -r examples/<your-example-folder>/requirements.txt

したがって、サンプルを追加する際は、requirements.txtファイルに、その学習サンプルに必要なすべてのpip依存関係を定義する必要があります。これにより、それらがすべてインストールされた状態で、ユーザーがサンプルの学習スクリプトを実行できるようになります。例えば、DreamBoothのrequirements.txtファイルを参照してください。

Diffusersライブラリの学習例は、以下の哲学に従う必要があります。

• 例を実行するために必要なすべてのコードは、単一のPythonファイルにまとめる必要があります。
• コマンドラインからpython <your-example>.py --argsで例を実行できるはずです。
• 例はシンプルに保ち、Diffusers をトレーニングに使用する方法の例として機能させるべきです。例スクリプトの目的は、最先端の拡散モデルを作成することではなく、そうではなく、過度なカスタムロジックを追加せずに既知のトレーニング手法を再現することです。この点の副産物として、私たちの例は、優れた教育資料としても機能することを目標としています。

例をコントリビュートする際は、dreamboothなどの既存の例を参照し、その構成のイメージを把握することをお強くお勧めします。 Diffusersと密に統合されているため、コントリビューターにはAccelerate libraryの利用を強く推奨します。 例のスクリプトが動作するようになったら、その例の正確な使い方を記述した包括的なREADME.mdを追加してください。このREADMEには、以下を含める必要があります:

• こちらに示されている例スクリプトを実行するためのコマンドの例です。
• ユーザーが期待できる内容を示す、こちらに示されているようなトレーニング結果（ログ、モデルなど）へのリンク。
• 非公式または研究用のトレーニング例を追加する場合は、お忘れなく、こちらに示されているように、このトレーニング例をメンテナンスしている旨の一文（git ハンドルを含む）を追加してください。

公式の学習サンプルに貢献される場合は、examples/dreambooth/test_dreambooth.py のように、そのフォルダーにテストを追加することも忘れないでください。非公式の学習サンプルには不要です。

8. 「Good second issue」の修正

Good second issuesには、Good second issueラベルが付与されています。これらは通常、Good first issuesよりも解決が複雑で、説明に修正に関するガイダンスが少なく、ライブラリに対するある程度の理解が求められます。

良い2番目の課題に取り組みたい場合は、その課題に対するご意見と、ご検討中のアプローチを数文でコメントとして共有し、PRを開く前にメンテナーから承認を得てください。すでにその課題に対してPRが開かれているがマージされていない場合は、新しい提案を行う前に、その理由を理解するために確認してください。

9. DiffusersのMVP issueに挑戦する

Diffusers MVPプログラムには、最も協力を求めている課題がリストアップされています。これらはGood second issuesと同様の仕組みですが、より難易度が高く、時間がかかるため、これに取り組む貢献者には報酬が提供されます。PRを開く前に、まずコメントでアプローチを共有し、メンテナーからの承認を得てください。このプログラムにはアイデアトラックも設けられており、Diffusersのインパクトを高めるアイデアを、実装詳細を含まない数文で教えてください。

10. パイプライン、モデル、スケジューラーの追加

モデルの作成者の方は、統合の調整のためご連絡ください。機能リクエストを開くか、すでに開かれている場合はコメントを残してください。

コミュニティの貢献者の方は、まず Hub のリポジトリから始めてください。Hub にパイプラインまたはモデルを公開するを参照し、機能リクエストの下に、アップストリームへの取り込みに関心がある旨をお知らせください。

Pipelines、models、schedulers は Diffusers ライブラリの最も重要な構成要素です。 これらは最先端の拡散技術への簡単なアクセスを提供し、コミュニティが強力な生成 AI アプリケーションを構築することを可能にします。

新しいモデル、パイプライン、またはスケジューラーを追加することで、Diffusers に依存するユーザーインターフェースのいずれにおいても、強力な新しいユースケースを有効にできる可能性があります。これは、生成AIエコシステム全体にとって非常に大きな価値をもたらすものです。

新しいモデルまたはパイプラインのサポートがリリースされた場合

新しいモデルやパイプラインをリリースに含める場合は、事前に Diffusers チームと統合について調整する必要があります。Diffusers リポジトリの issue 経由、または [email protected] へのメールで、お気軽にお問い合わせください。

モデルやパイプラインのプルリクエストがマージされた時点で、リリースが自動的に実行されるわけではありません。リリース前に、メンテナーは統合が完了していること、およびリリーステストがパスしていることを確認します。

新しいモデルまたはパイプラインのサポートは、通常、次のマイナーリリースに組み込まれます。統合はmainにマージされ、リリースブランチはそこから作成されます。リリースには、モデルやパイプラインの統合だけでなく、前回のリリース以降にマージされたすべての変更が含まれます。

リリースノートでは、新しいモデルやパイプラインを強調するとともに、そのリリースに含まれるその他の変更点も要約します。パッチリリースは、既存のリリースに対する修正に通常使用されます。

Diffusersには、すべての3つのコンポーネントに関するオープンな機能リクエストがいくつかあります。追加したい具体的なコンポーネントがまだ決まっていない場合は、ざっと目を通すだけでも構いません:

• モデルまたはパイプライン
• スケジューラ

3つのコンポーネントのいずれかを追加する前に、Philosophy guide をお読みいただき、3つのコンポーネントの設計をより深く理解することをお強くお勧めします。当社の設計思想から大きく逸脱するモデル、スケジューラ、またはパイプラインの追加は、APIの不一致を招くため、マージすることができません。設計上の判断に根本的な異議がある場合は、特定の設計パターンや設計判断をライブラリ全体で変更すべきか、また設計思想を更新すべきかを議論するために、代わりにFeedback issue を作成してください。ライブラリ全体での一貫性は、当社にとって非常に重要です。

PRには、元のコードベースや論文へのリンクを必ず追加してください。また、可能であれば、PR上で元の著者にも直接通知し、進捗を追跡してもらったり、質問への回答を依頼したりできるようにしてください。

PRで不確かな点がある場合や、進め方に詰まった場合は、ためらわずにメッセージを残して、最初のレビューやサポートを依頼してください。

メカニズムからコピー

パイプライン、モデル、またはスケジューラのコードを追加する際に理解すべき、ユニークかつ重要な機能として、# Copied fromメカニズムがあります。Diffusersのコードベース全体でこのメカニズムを目にしますが、コードベースを分かりやすく保守しやすい状態に保つために使用しています。# Copied fromメカニズムでマークされたコードは、コピー元のコードと完全に同一であることが強制されます。これにより、make fix-copiesを実行するたびに、変更を多数のファイルにわたって容易に更新・反映できます。

例えば、以下のコード例では、StableDiffusionPipelineOutput が元のコードであり、AltDiffusionPipelineOutput は # Copied from メカニズムを使用してそれをコピーしています。唯一の違いは、クラスプレフィックスを Stable から Alt に変更している点です。

# Copied from diffusers.pipelines.stable_diffusion.pipeline_output.StableDiffusionPipelineOutput with Stable->Alt
class AltDiffusionPipelineOutput(BaseOutput):
    """
    Output class for Alt Diffusion pipelines.

    Args:
        images (`List[PIL.Image.Image]` or `np.ndarray`)
            List of denoised PIL images of length `batch_size` or NumPy array of shape `(batch_size, height, width,
            num_channels)`.
        nsfw_content_detected (`List[bool]`)
            List indicating whether the corresponding generated image contains "not-safe-for-work" (nsfw) content or
            `None` if safety checking could not be performed.
    """

詳細については、~Don’t~ Repeat Yourself*ブログ記事の該当セクションをお読みください。

良いIssueの書き方

Issueの記述が丁寧であればあるほど、迅速に解決される可能性が高くなります。

1. 問題の投稿に正しいテンプレートを使用していることを確認してください。Bug Report、Feature Request、Feedback about API Design、New model/pipeline/scheduler addition、または空のテンプレートから選択できます。新しい問題を開く際に、適切なものを選択してください。使用方法に関する質問は、問題ではなくGitHub Discussionsで扱うべきです。
2. 正確に記述する: 問題にふさわしいタイトルを付けます。問題の説明は、できるだけ簡潔に記述してください。問題を報告する際に正確であればあるほど、問題の理解と解決にかかる時間が短縮されます。1つの問題につき1つのissueを開き、複数の問題について1つのissueを開かないようにしてください。複数の問題が見つかった場合は、それぞれにissueを開いてください。問題がバグである場合は、どのバグであるかをできるだけ正確に記述してください。「diffusersでエラーが発生した」のような曖昧な記述は避けてください。
3. Reproducibility: No reproducible code snippet == no solution. If you encounter a bug, maintainers have to be able to reproduce it. Make sure that you include a code snippet that can be copy-pasted into a Python interpreter to reproduce the issue. Make sure that your code snippet works, i.e. that there are no missing imports or missing links to images, … Your issue should contain an error message and a code snippet that can be copy-pasted without any changes to reproduce the exact same error message. If your issue is using local model weights or local data that cannot be accessed by the reader, the issue cannot be solved. If you cannot share your data or model, try to make a dummy model or dummy data.
4. 最小限に: 可能な限り簡潔に記述し、読者が問題を素早く理解できるよう努めてください。問題に関連しないコードや情報はすべて削除してください。バグを発見した場合、問題を示すための最もシンプルなコード例を作成してください。バグを発見したからといって、ワークフロー全体をそのまま問題報告に貼り付けるのは避けてください。例えば、モデルの学習中にエラーが発生した場合、まず学習コードのどの部分がエラーの原因かを理解し、数行のコードで再現を試みてください。完全なデータセットではなく、ダミーデータを使用するようにしてください。
5. 背景: バグが発生した、または機能が必要になった際に、何に取り組んでいたかをお知らせください。Diffusers をベースに構築したアプリケーション、研究プロジェクト、ライブラリのバグ探索を実行したエージェントなどです。1〜2文で十分です。プロジェクトへのリンクも歓迎します。一度に処理できる以上の数の Issue と PR が寄せられるため、背景情報があると、影響度に基づいて優先順位をつけるのに役立ちます。
6. リンクを追加してください。特定の命名規則、メソッド、モデルについて言及する場合は、読者が何を指しているかをより正確に理解できるよう、必ずリンクを付けてください。特定のPRやissueについて言及する場合は、必ず該当するissueへのリンクを付けてください。読者が何を話しているかを知っているとは前提せず、issueに追加するリンクは多いほど良いです。
7. 書式設定。コードは Python のコード構文、エラーメッセージは通常のコード構文として整形し、Issue を適切に書式設定してください。詳細については、GitHub 公式の書式設定ドキュメントを参照してください。
8. 問題を「解決すべきチケット」としてではなく、よく書かれた百科事典の美しい一項目として捉えてください。追加される各問題は、公開されている知識への貢献です。丁寧に記述された問題を追加することで、メンテナーが問題を解決しやすくなるだけでなく、コミュニティ全体がライブラリの特定の側面をより深く理解する手助けにもなります。

良いPRの書き方

1. 常に issue から始めてください。Pull request が対応する issue を見つけてください。まだ誰も作成していない場合は issue を作成し、コードを書く前にメンテナーが回答する機会を与えてください。私たちが最も効果的だと感じているワークフローは、まず issue を作成し、次に解決策について議論し、その議論に基づいて PR を作成するというものです。これにより、最もインパクトのある issue に時間を集中させ、コードが存在する前にスコープについて合意し、重複した作業を回避できます。PR の説明に issue 番号を記載（例: Fixes #1234）し、両者をリンクしてください。
2. カメレオンのように振る舞いましょう。既存の設計パターンや構文を理解し、追加するコードが既存のコードベースに自然に溶け込むことを確認してください。既存の設計パターンやユーザーインターフェースから大きく逸脱する Pull Request はマージされません。
3. 一点に集中してください。プルリクエストは、1つの問題、それも1つの問題のみを解決するべきです。「ついでにもう1つの問題も修正しよう」という罠に陥らないように注意してください。複数の無関係な問題を同時に解決するプルリクエストは、レビューがはるかに困難になります。
4. パターンを修正し、個別のケースに留まらないでください。1つの問題が複数のファイルにまたがっている場合があります。同じバグがコードベース全体に繰り返し現れている場合は、すべてのインスタンスを検索し、明確で体系的なスコープ（例：「すべてのスケジューラでミュータブルなデフォルト値を修正」）を定めた1つのPRでまとめて修正してください。インスタンスごとに1つのPRを立てるのではなく、そうしてください。
5. プルリクエストのタイトルは、その貢献内容の要約であるべきです。作業中であることを示すには、タイトルの先頭に[WIP]を付けます。これにより、重複した作業を避け、マージ可能なPRと区別できます。
6. 良いIssueの書き方で説明されているように、テキストを構成し、フォーマットしてください。
7. PR を作成する前に、自分の diff を確認してください。レビュアーの視点で読み、見つかった問題を修正してください。self-review スキルを実行することを強く推奨します。このスキルは、@claude CI レビュアーと同じ評価基準を実行します。AI エージェントによるコーディング に記載されているようにエージェントを設定し、AI 支援およびエージェントによる貢献 に従ってください。説明欄には、意図的にそのままにした発見事項を記載し、レビュアーがそれが意図的な判断であり見落としではないことを理解できるようにしてください。
8. 既存のテストがパスすることを確認してください。
9. 高カバレッジのテストを追加してください。品質テストなしではマージできません。

• 新しい@slowテストを追加する場合は、RUN_SLOW=1 python -m pytest tests/test_my_new_model.pyを実行してテストがパスすることを確認してください。 CircleCIではslowテストは実行されませんが、GitHub Actionsでは毎晩実行されます！

10. すべての公開メソッドには、Markdown と相性の良い、有益な docstring を付ける必要があります。例として pipeline_latent_diffusion.py を参照してください。
11. リポジトリの急速な成長に伴い、リポジトリのサイズを大幅に増加させるファイルを追加しないよう注意することが重要です。これには、画像、動画、その他のテキスト以外のファイルが含まれます。これらのファイルを配置するには、hf-internal-testing や huggingface/documentation-images のような、hf.co でホストされている dataset を活用することを推奨します。 外部からの貢献の場合、PR に画像を追加し、Hugging Face のメンバーにこれらの画像を当該 dataset へ移行するよう依頼してください。

PRの作成方法

コードを書く前に、既存のPRやissueを検索し、同じ内容にすでに誰かが取り組んでいないことを確認することを強くお勧めします。不確かな場合は、フィードバックを得るためにissueを立てることを検討してください。

🧨 Diffusers に貢献するには、基本的な git の知識が必要です。git は最も使いやすいツールというわけではありませんが、最高のマニュアルが用意されています。シェルで git --help と入力して、その便利さを体験してみてください。書籍を好む方には、Pro Git が非常に優れた参考書です。

貢献を始めるには、以下の手順に従ってください（サポートされている Python のバージョン）：

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

2. フォークをローカルディスクにクローンし、ベースリポジトリをリモートとして追加します:

   コピーしました

   $ git clone [email protected]:<your GitHub handle>/diffusers.git
   $ cd diffusers
   $ git remote add upstream https://github.com/huggingface/diffusers.git

3. 開発中の変更を保持するために新しいブランチを作成します:

   コピーしました

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

main ブランチで作業しないでください。

4. 仮想環境で次のコマンドを実行して、開発環境を設定します:

   コピーしました

   $ pip install -e ".[dev]"

リポジトリをすでにクローンしている場合は、ライブラリの最新の変更を取得するためにgit pullを実行する必要がある場合があります。

5. ブランチ上で機能を開発してください。

機能の開発を進める際は、テストスイートがパスすることを確認してください。変更の影響を受けるテストは、次のように実行してください。

$ pytest tests/<TEST_TO_RUN>.py

テストを実行する前に、テストに必要な依存関係がインストールされていることを確認してください。以下のコマンドで実行できます:

$ pip install -e ".[test]"

以下のコマンドでテストスイート全体を実行することもできますが、Diffusersが大幅に成長したため、適切な時間で結果を得るには高性能なマシンが必要です。コマンドは以下の通りです:

$ make test

🧨 Diffusers はソースコードの一貫したフォーマットに black と isort を使用しています。変更を加えた後、以下のコマンドで自動的なスタイル修正と、自動化できないコード検証を一度に実行できます。

$ make style

🧨 Diffusers は ruff と一部のカスタムスクリプトを使用して、コーディングミスをチェックします。品質管理は CI で実行されますが、同じチェックを以下で実行することもできます。

$ make quality

変更内容に満足したら、git add を使用して変更されたファイルをステージングし、git commit を使用してコミットを作成して、ローカルで変更を記録します:

$ git add modified_file.py
$ git commit -m "A descriptive message about your changes."

コードのコピーを元のリポジトリと定期的に同期させることをお勧めします。これにより、変更を素早く反映できます。

$ git pull upstream main

以下を使用して、変更をアカウントにプッシュします:

$ git push -u origin a-descriptive-name-for-my-changes

6. ご満足いただけたら、GitHub 上のフォークのウェブページに移動してください。「Pull request」をクリックして、変更内容をプロジェクトのメンテナーにレビュー依頼として送信します。

7. メンテナージャーから変更を求められることがあっても、それは問題ありません。コアコントリビューターにもよくあることです。Pull request で変更内容が誰でも確認できるようにするため、ローカルブランチで作業し、変更をフォークにプッシュしてください。すると、Pull request に自動的に反映されます。

テスト

ライブラリの動作と複数の例をテストするための広範なテストスイートが含まれています。ライブラリのテストはtestsフォルダにあります。

pytest と pytest-xdist は高速であるため、こちらを推奨しています。リポジトリのルートディレクトリから、ライブラリのテストを pytest で実行するには、以下の手順を実行します。

$ python -m pytest -n auto --dist=loadfile -s -v ./tests/

実際、make test はこのように実装されています!

作業中の機能のみをテストするために、テストのセットを小さく指定できます。

デフォルトでは、低速なテストはスキップされます。RUN_SLOW 環境変数を yes に設定すると、これらが実行されます。これにより、数 GB のモデルがダウンロードされるため、十分なディスク容量と安定したインターネット接続、あるいはかなりの忍耐強さが必要です。

$ RUN_SLOW=yes python -m pytest -n auto --dist=loadfile -s -v ./tests/

unittest は完全にサポートされており、テストを実行するには次のようにします。

$ python -m unittest discover -s tests -t . -v
$ python -m unittest discover -s examples -t examples -v

フォークした main をアップストリーム（HuggingFace）の main と同期する

各アップストリームPRに参照注釈を追加し、これらのPRに関与している開発者に不要な通知を送信してしまうことを避けるため、フォークされたリポジトリのmainブランチを同期する際は、以下の手順に従ってください。

1. 可能であれば、フォークしたリポジトリでブランチとPRを使ってアップストリームと同期するのを避けましょう。代わりに、フォークのmainに直接マージしてください。
2. PRがどうしても必要な場合は、ブランチをチェックアウトした後に、以下の手順を実行してください。

$ git checkout -b your-branch-for-syncing
$ git pull --squash --no-commit upstream main
$ git commit -m '<your message without GitHub references>'
$ git push --set-upstream origin your-branch-for-syncing

スタイルガイド

ドキュメント文字列については、🧨 Diffusers は Google スタイル に従います。

AIエージェントによるコーディング

このリポジトリでは、AIエージェントの設定を.ai/に保存しています。また、エージェントプラグインとしても公開されているため、オンデマンドのタスクスキルを1ステップでインストールできます。

• コントリビューターは読み取り専用 — .ai/ はコアメンテナーによって管理されています。.ai/ 配下のファイル（ルートレベルの AGENTS.md / CLAUDE.md シンボリックリンク、またはインストール済みの .agents/skills / .claude/skills を含む）を PR で編集しないでください。不足や誤りを見つけた場合は、Issue を作成するか PR で指摘してください。メンテナーが更新します。
• Guidelines — .ai/AGENTS.md はルートディレクトリの AGENTS.md / CLAUDE.md シンボリックリンクを介して、すべてのエージェントセッションに読み込まれます。 .ai/references/ 以下のリファレンスガイドは、リンクが追跡された際に必要に応じて読み込まれます:
  • .ai/AGENTS.md — トップレベルのコーディングガイドライン
  • .ai/references/models.md — アテンションパターン、モデル実装ルール、一般的な慣習
  • .ai/references/pipelines.md — パイプラインの規約
  • .ai/references/modular.md — モジュラーパイプラインの規約と変換チェックリスト
  • .ai/references/testing.md — 必須のテストレイヤー、テスターミックスイン、ダミーコンポーネントのルール
  • .ai/references/review-rules.md — レビュアーが確認する項目
• Skills (下 .ai/skills/, 特定のタスクに応じてオンデマンドで読み込まれます):
  • model-integration — diffusers に新しいモデルまたはパイプラインをエンドツーエンドで追加する（ファイル構成、統合チェックリスト、テストの構成、重みの変換）
  • self-review — PR を作成する前に、プロジェクトのルールに照らして変更内容を確認します
  • diffusers-cli — ターミナルからパイプラインの実行とスキーマの確認
  • custom-blocks — Hub 向けに ModularPipelineBlocks のサブクラスをパッケージングする

どの方法を選択しても、開始前にエージェントに自身のセットアップを確認させてください。python utils/check_ai.py はガイドとスキルの一貫性をチェックし、diffusers-cli skills list は実際に保有しているスキルを表示します。

AI支援およびエージェント型コントリビューション

AIエージェントによるDiffusersへの貢献も歓迎します。Diffusersのエージェントガイドに従ってエージェントを設定し、model-integrationやself-reviewなどの関連するタスク固有のスキルを使用してください。上記の手順に従ってプラグイン（または個々のスキル）をインストールし、ガイドに従って貢献のスコープ設定、実装、テスト、レビューを行ってください。PR内の変更を理解し、テストし、維持する責任は引き続きあなたにあります。

AI支援による貢献は歓迎されますが、レビュー負荷を管理可能な範囲に抑えるため、調整、スコープの明確化、検証が必要です。これらのガイドラインに従わないPRは、詳細なレビューなしでクローズされる場合があります。

• PR を作成する前に調整を行う。 関連する issue を検索するか新規に作成し、類似の PR（オープン中および最近クローズされたもの）を確認したうえで、その issue に対してメンテナーから明示的な承認を得てから PR を作成してください。これにより、スコープについて議論し、重複した作業を避け、アプローチを確認する機会が得られます。
• パターンを修正し、個別のケースに留めないでください。 繰り返し発生する問題が見つかった場合は、コードベース内で同様のインスタンスを検索し、個別のインスタンスごとに多数の issue や PR を作成するのではなく、明確で体系的なスコープ（例:「すべての scheduler で mutable なデフォルト値を修正する」）を指定した1つの issue を作成してください。
• PR を作成する前のセルフレビュー。 self-review スキルを実行してください。このスキルは、@claude CI レビュアーが使用するのと同じ基準である .ai/references/review-rules.md に基づいて diff をレビューし、報告された問題に対処します。これは権威あるものではなく、誤りを含む可能性のあるヘルパーです。あなたにとって妥当なブロッキング問題に焦点を当て、不要なコードや未使用のコードを可能な限り整理してください。提案に同意しない場合は、PR を開いた後にレビュアーと議論するためにそのまま残して構いません。共有するメモ（下記参照）により、それが意図的な判断であったことがレビュアーに伝わるためです。
• セルフレビューのメモを共有してください。 提出する diff を反映した最終ラウンドのセルフレビューレポートを、PR の説明欄またはコメントとして投稿してください。意図的に修正しなかった指摘事項とその理由も含めてください。これにより、レビュアーはすでに確認済みの内容や意図的な判断を把握でき、通常は数回のやり取りを省くことができます。
• PRのコミュニケーションは簡潔に保ちましょう。 レビュアーがPRで読むものすべて — 説明、コミットメッセージ、コメントと返信、コード内のコメント — は、人間が理解しやすいものでなければなりません。エージェントが作成した場合は、軽く目を通すだけでは不十分です。実際に読み、自分が自然に書くような、意味が通じ簡潔な内容になるまでエージェントに修正を依頼してください。あなたが投稿するすべての内容の著者は、あなた自身です。
• Include in the PR description:
  • メンテナがその作業を承認したイシューまたはディスカッションへの調整リンク。
  • 実行したテストコマンドとその結果（「テストがパスした」だけでなく、関連する出力を貼り付けてください）。
  • 上記で説明した、あなたのセルフレビューノート（またはそれを含むPRコメントへのリンク）。

モデルの作成者、または公式にモデルをメンテナンスしているチームの一員である場合は、新しいモデルの統合にエージェントの使用を推奨します。リポジトリの推奨セットアップに従い、model-integrationスキルを使用してください。PR を作成する前に、スコープをメンテナーと調整してください。パイプライン、モデル、スケジューラーの追加を参照してください。