Hugging Face 的 LOGO

Diffusers 文件

如何為 Diffusers 做出貢獻 🧨

Hugging Face's logo
加入 Hugging Face 社群

並獲得增強的文件體驗

開始使用

如何為 Diffusers 做出貢獻 🧨

我們 ❤️ 來自開源社群的貢獻！我們歡迎所有人，並且所有型別的參與——不僅僅是程式碼——都受到重視和讚賞。回答問題、幫助他人、聯絡溝通以及改進文件對社群都非常有價值，所以如果你願意，請不要害怕並參與進來！

我們鼓勵大家先在我們的公共 Discord 頻道中說聲 👋。我們討論擴散模型的最新趨勢、提問、展示個人專案、在貢獻方面互相幫助，或者只是閒逛 ☕。Join us on Discord

無論你選擇哪種方式貢獻，我們都努力成為一個開放、熱情和友善的社群的一份子。請閱讀我們的行為準則，並在互動中注意遵守。我們還建議你熟悉指導我們專案的道德準則，並請你遵守同樣的透明和負責任原則。

我們非常重視來自社群的反饋，所以如果你認為你有寶貴的反饋可以幫助改進這個庫，請不要害怕說出來——每一條訊息、評論、問題和拉取請求（PR）都會被閱讀和考慮。

概述

你可以透過多種方式做出貢獻，從在 issue 和 discussion 中回答問題，到向核心庫新增新的擴散模型。

下面，我們概述了不同的貢獻方式，按難度升序排列。所有這些對社群都很有價值。

如前所述，所有貢獻對社群都很有價值。下面，我們將更詳細地解釋每種貢獻。

對於所有 4 - 9 的貢獻，你都需要開啟一個 PR。在開啟一個拉取請求中有詳細說明。

1. 在 Diffusers 討論區或 Diffusers Discord 上提問和回答問題

任何與 Diffusers 庫相關的問題或評論都可以在討論區或 Discord 上提問。這類問題和評論包括（但不限於）：

  • 分享知識的訓練或推理實驗報告
  • 個人專案展示
  • 關於非官方訓練示例的問題
  • 專案提案
  • 一般反饋
  • 論文摘要
  • 在基於 Diffusers 庫構建的個人專案中尋求幫助
  • 一般性問題
  • 關於擴散模型的倫理問題
  • ...

在論壇或 Discord 上提出的每個問題都積極鼓勵社群公開分享知識，並且很可能在未來幫助到有同樣問題的初學者。請隨時提出你可能有的任何問題。本著同樣的精神，透過回答這些問題，你對社群的幫助是巨大的，因為這樣你就在為每個人公開記錄知識，供大家學習。

請記住，你在提問或回答問題上投入的精力越多，公開記錄的知識質量就越高。同樣，提問得好、回答得好的問題會建立一個高質量的知識庫，供所有人訪問，而提問得差或回答得差的問題會降低公共知識庫的整體質量。簡而言之，一個高質量的問題或回答是*精確*、*簡潔*、*相關*、*易於理解*、*易於訪問*和*格式/提問良好*的。更多資訊，請檢視如何寫一個好的 issue部分。

關於渠道的說明：論壇更容易被搜尋引擎（如谷歌）索引。帖子按受歡迎程度而非時間順序排名。因此，查詢我們前段時間釋出的問題和答案更容易。此外，論壇上釋出的問題和答案可以輕鬆連結。相比之下，Discord 具有類似聊天的格式，適合快速的來回交流。雖然在 Discord 上你的問題很可能更快得到答案，但隨著時間的推移，你的問題將不再可見。而且，在 Discord 上找到很久以前釋出的資訊要困難得多。因此，我們強烈建議使用論壇進行高質量的提問和回答，以期為社群創造持久的知識。如果 Discord 上的討論產生了非常有趣的答案和結論，我們建議將結果釋出在論壇上，以便未來的讀者更容易獲取這些資訊。

2. 在 GitHub issues 標籤頁上開啟新的 issue

🧨 Diffusers 庫的穩健和可靠得益於使用者們告知我們他們遇到的問題。所以感謝你報告一個 issue。

請記住，GitHub issues 是為直接與 Diffusers 庫相關的技術問題、錯誤報告、功能請求或對庫設計的反饋而設的。

簡而言之，這意味著所有與 Diffusers 庫的程式碼（包括文件）無關 的事情都不應該在 GitHub 上提問，而應該在論壇或 Discord 上提問。

在開啟新的 issue 時，請考慮以下準則：:

  • 確保你已經搜尋過你的問題是否已經被提出過（使用 GitHub Issues 下的搜尋欄）。
  • 請永遠不要在另一個（相關的）issue 上報告一個新的 issue。如果另一個 issue 高度相關，請仍然開啟一個新的 issue，並連結到相關的 issue。
  • 確保你的 issue 是用英文寫的。如果你對英語不自信，請使用像 DeepL 這樣優秀的免費線上翻譯服務，將你的母語翻譯成英語。
  • 檢查你的問題是否可以透過更新到最新的 Diffusers 版本來解決。在釋出你的 issue 之前，請確保 `python -c "import diffusers; print(diffusers.__version__)"` 的版本高於或匹配最新的 Diffusers 版本。
  • 請記住，你在開啟新 issue 時投入的精力越多，你的答案質量就會越高，Diffusers issues 的整體質量也會更好。

新的 issue 通常包括以下內容。

2.1. 可復現的、最小化的錯誤報告

錯誤報告應該總是包含一個可復現的程式碼片段，並且儘可能地最小化和簡潔。具體來說：

  • 儘可能地縮小錯誤的範圍，不要只是把你整個程式碼檔案都扔上來。
  • 格式化你的程式碼。
  • 除了 Diffusers 依賴的外部庫之外，不要包含任何其他外部庫。
  • 總是提供關於你環境的所有必要資訊；為此，你可以在你的 shell 中執行：`diffusers-cli env`，然後將顯示的資訊複製貼上到 issue 中。
  • 解釋問題。如果讀者不知道問題是什麼，以及為什麼這是一個問題，他（她）就無法解決它。
  • 總是確保讀者能以最少的努力復現你的問題。如果你的程式碼片段因為缺少庫或未定義的變數而無法執行，讀者就無法幫助你。確保你的可復現程式碼片段儘可能地最小化，並且可以被複制貼上到一個簡單的 Python shell 中執行。
  • 如果為了復現你的問題需要一個模型和/或資料集，確保讀者能夠訪問那個模型或資料集。你總是可以把你的模型或資料集上傳到 Hub，以便於下載。儘量保持你的模型和資料集儘可能小，以便復現你的問題儘可能地輕鬆。

更多資訊，請檢視如何寫一個好的 issue部分。

你可以在這裡開啟一個錯誤報告。

2.2. 功能請求

一個世界級的功能請求應該解決以下幾點：

  1. 動機優先
  • 它是否與庫中的問題/困擾有關？如果是，請解釋原因。提供一個展示問題的程式碼片段是最好的。
  • 它是否與你專案需要的東西有關？我們很樂意瞭解！
  • 這是你做過的並且認為可以造福社群的東西嗎？太棒了！告訴我們它為你解決了什麼問題。
  1. 寫一個*完整的段落*來描述這個功能；
  2. 提供一個展示其未來用法的**程式碼片段**；
  3. 如果這與一篇論文有關，請附上鍊接；
  4. 附上你認為有幫助的任何額外資訊（圖紙、截圖等）。

你可以在這裡開啟一個功能請求。

2.3 反饋

關於庫設計的反饋，以及它好或不好的原因，極大地幫助核心維護者構建一個使用者友好的庫。要理解當前設計理念背後的哲學，請檢視這裡。如果你覺得某個設計選擇不符合當前的設計理念，請解釋為什麼以及應該如何改變。如果某個設計選擇過於遵循設計理念，從而限制了使用場景，請解釋為什麼以及應該如何改變。如果某個設計選擇對你非常有用，也請留言，因為這是對未來設計決策的極好反饋。

你可以在這裡開啟一個關於反饋的 issue。

2.4 技術問題

技術問題主要關於庫的某些程式碼為何以某種方式編寫，或者某部分程式碼的作用。請確保連結到相關的程式碼，並詳細說明為什麼這部分程式碼難以理解。

你可以在這裡開啟一個關於技術問題的 issue。

2.5 提議新增新模型、排程器或 pipeline

如果擴散模型社群釋出了你希望在 Diffusers 庫中看到的新模型、pipeline 或排程器，請提供以下資訊：

  • 擴散 pipeline、模型或排程器的簡要描述，並附上論文或公開發布的連結。
  • 其任何開源實現的連結。
  • 如果模型權重可用，請提供連結。

如果你願意自己為模型做貢獻，請告訴我們，以便我們能最好地指導你。另外，如果能找到，請不要忘記在 GitHub 上標記元件（模型、排程器、pipeline 等）的原始作者。

你可以在這裡開啟一個模型/pipeline/排程器的請求。

3. 在 GitHub issues 標籤頁上回答 issue

在 GitHub 上回答 issue 可能需要一些關於 Diffusers 的技術知識，但我們鼓勵每個人都嘗試一下，即使你不是 100% 確定你的答案是正確的。給出高質量 issue 回答的一些技巧：

  • 儘可能簡潔和最小化。
  • 保持主題。對 issue 的回答應該只關注該 issue。
  • 提供指向程式碼、論文或其他來源的連結，以證明或支援你的觀點。
  • 用程式碼回答。如果一個簡單的程式碼片段是 issue 的答案或展示瞭如何解決問題，請提供一個完全可復現的程式碼片段。

此外，許多 issue 往往是跑題、與其他 issue 重複或無關的。如果你能回答這類 issue，鼓勵 issue 的作者更精確、提供重複 issue 的連結或將他們引導到論壇或 Discord，這對維護者來說是極大的幫助。

如果你已經驗證了釋出的錯誤報告是正確的，並且需要在原始碼中進行修正，請檢視接下來的部分。

對於以下所有貢獻，你都需要開啟一個 PR。在開啟一個拉取請求部分有詳細說明。

4. 修復一個“Good first issue”

Good first issues 由 Good first issue 標籤標記。通常，issue 已經解釋了一個潛在的解決方案應該是什麼樣子，以便更容易修復。如果 issue 尚未關閉，並且你想嘗試修復此 issue，你可以留言說“我想嘗試這個 issue。” 通常有三種情況：

  • a.) issue 描述已經提出了一個修復方案。在這種情況下，如果解決方案對你來說有意義，你可以開啟一個 PR 或草稿 PR 來修復它。
  • b.) issue 描述沒有提出修復方案。在這種情況下，你可以詢問一個提議的修復方案可能是什麼樣子，Diffusers 團隊的某個人應該會很快回答。如果你對如何修復它有很好的想法，可以直接開啟一個 PR。
  • c.) 已經有一個開放的 PR 來修復該 issue，但該 issue 尚未關閉。如果該 PR 已經過時，你可以簡單地開啟一個新的 PR 並連結到過時的 PR。如果最初想修復 issue 的貢獻者突然沒有時間繼續，PR 往往會過時。這在開源中經常發生，非常正常。在這種情況下，如果你能重新嘗試並利用現有 PR 的知識，社群會非常高興。如果已經有一個 PR 並且是活躍的，你可以透過給出建議、審查 PR 甚至詢問是否可以為該 PR 做出貢獻來幫助作者。

5. 為文件做貢獻

一個好的庫**總是**有好的文件！官方文件通常是庫的新使用者的第一個接觸點，因此為文件做貢獻是**非常有價值的貢獻**。

為庫做貢獻可以有多種形式：

  • 糾正拼寫或語法錯誤。
  • 糾正文件字串的錯誤格式。如果你看到官方文件顯示奇怪或連結損壞，我們非常高興你花時間糾正它。
  • 糾正文件字串輸入或輸出張量的形狀或維度。
  • 澄清難以理解或不正確的文件。
  • 更新過時的程式碼示例。
  • 將文件翻譯成另一種語言。

在官方 Diffusers 文件頁面上顯示的任何內容都是官方文件的一部分，可以在相應的文件源中進行更正、調整。

請檢視此頁面，瞭解如何在本地驗證對文件所做的更改。

6. 貢獻一個社群 pipeline

閱讀社群 pipeline指南，瞭解 GitHub 和 Hugging Face Hub 社群 pipeline 之間的區別。如果你對我們為什麼有社群 pipeline 感興趣，可以看看 GitHub Issue #841（基本上，我們無法維護擴散模型可用於推理的所有可能方式，但我們也不想阻止社群構建它們）。

貢獻一個社群 pipeline 是與社群分享你的創造力和工作的好方法。它讓你可以在 DiffusionPipeline 的基礎上構建，這樣任何人都可以透過設定 `custom_pipeline` 引數來載入和使用它。本節將引導你建立一個簡單的 pipeline，其中 UNet 只進行一次前向傳播並呼叫排程器一次（一個“一步式” pipeline）。

  1. 為你的社群 pipeline 建立一個 one_step_unet.py 檔案。這個檔案可以包含你想要使用的任何包，只要使用者安裝了它。確保你只有一個繼承自 DiffusionPipeline 的 pipeline 類，以便從 Hub 載入模型權重和排程器配置。在 `__init__` 函式中新增一個 UNet 和排程器。

    你還應該新增 `register_modules` 函式，以確保你的 pipeline 及其元件可以使用 save_pretrained() 儲存。

from diffusers import DiffusionPipeline
import torch

class UnetSchedulerOneForwardPipeline(DiffusionPipeline):
    def __init__(self, unet, scheduler):
        super().__init__()

        self.register_modules(unet=unet, scheduler=scheduler)
  1. 在前向傳播（我們建議定義為 `__call__`）中，你可以新增任何你想要的功能。對於“一步式” pipeline，建立一個隨機影像，並透過設定 `timestep=1` 來呼叫 UNet 和排程器一次。
  from diffusers import DiffusionPipeline
  import torch

  class UnetSchedulerOneForwardPipeline(DiffusionPipeline):
      def __init__(self, unet, scheduler):
          super().__init__()

          self.register_modules(unet=unet, scheduler=scheduler)

      def __call__(self):
          image = torch.randn(
              (1, self.unet.config.in_channels, self.unet.config.sample_size, self.unet.config.sample_size),
          )
          timestep = 1

          model_output = self.unet(image, timestep).sample
          scheduler_output = self.scheduler.step(model_output, timestep, image).prev_sample

          return scheduler_output

現在，你可以透過向其傳遞一個 UNet 和排程器來執行 pipeline，或者如果 pipeline 結構相同，則載入預訓練權重。

from diffusers import DDPMScheduler, UNet2DModel

scheduler = DDPMScheduler()
unet = UNet2DModel()

pipeline = UnetSchedulerOneForwardPipeline(unet=unet, scheduler=scheduler)
output = pipeline()
# load pretrained weights
pipeline = UnetSchedulerOneForwardPipeline.from_pretrained("google/ddpm-cifar10-32", use_safetensors=True)
output = pipeline()

你可以將你的 pipeline 作為 GitHub 社群 pipeline 或 Hub 社群 pipeline 分享。

GitHub pipeline
Hub pipeline

透過在 Diffusers 倉庫上開啟一個拉取請求，並將 one_step_unet.py 檔案新增到 examples/community 子資料夾中，來分享你的 GitHub pipeline。

7. 為訓練示例做貢獻

Diffusers 示例是位於 examples 中的一系列訓練指令碼。

我們支援兩種型別的訓練示例：

  • 官方訓練示例
  • 研究性訓練示例

研究性訓練示例位於 examples/research_projects，而官方訓練示例包括 examples 下的所有資料夾，除了 `research_projects` 和 `community` 資料夾。官方訓練示例由 Diffusers 的核心維護者維護，而研究性訓練示例由社群維護。這是出於與6. 貢獻一個社群 pipeline中提出的官方 pipeline 與社群 pipeline 相同的原因：核心維護者不可能維護擴散模型的所有可能的訓練方法。如果 Diffusers 核心維護者和社群認為某個訓練正規化過於實驗性或不夠流行，相應的訓練程式碼應該放在 `research_projects` 資料夾中，並由作者維護。

官方訓練和研究示例都包含一個目錄，該目錄包含一個或多個訓練指令碼、一個 `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，以瞭解它們應該是什麼樣子。我們強烈建議貢獻者使用 Accelerate 庫，因為它與 Diffusers 緊密整合。一旦示例指令碼可以工作，請確保新增一個全面的 `README.md`，說明如何準確使用該示例。這個 README 應該包括：

  • 一個如何執行示例指令碼的示例命令，如這裡所示。
  • 一些訓練結果（日誌、模型等）的連結，展示使用者可以期待的結果，如這裡所示。
  • 如果你正在新增一個非官方/研究性訓練示例，**請不要忘記**新增一句話，說明你正在維護這個訓練示例，幷包括你的 git 控制代碼，如這裡所示。

如果你正在為官方訓練示例做貢獻，請確保也為其資料夾新增一個測試，例如 examples/dreambooth/test_dreambooth.py。對於非官方訓練示例，這不是必需的。

8. 修復一個“Good second issue”

Good second issues 由 Good second issue 標籤標記。Good second issues 通常比 Good first issues 更復雜。issue 描述通常對如何修復問題提供的指導較少，並且需要感興趣的貢獻者對庫有相當的理解。如果你有興趣解決一個 good second issue，可以直接開啟一個 PR 來修復它，並將 PR 連結到該 issue。如果你看到已經為該 issue 開啟了一個 PR 但尚未合併，請檢視原因並嘗試開啟一個改進的 PR。Good second issues 通常比 good first issues 更難合併，所以不要猶豫向核心維護者尋求幫助。如果你的 PR 差不多完成了，核心維護者也可以加入你的 PR 並提交程式碼，以使其合併。

9. 新增 pipelines、模型、排程器

Pipelines、模型和排程器是 Diffusers 庫中最重要的部分。它們提供了對最先進的擴散技術的便捷訪問，從而使社群能夠構建強大的生成式 AI 應用。

透過新增一個新的模型、pipeline 或排程器，你可能會為依賴 Diffusers 的任何使用者介面啟用一個新的強大用例，這對於整個生成式 AI 生態系統來說都具有巨大的價值。

Diffusers 對所有這三個元件都有一些開放的功能請求——如果你還不知道想新增哪個特定元件，可以瀏覽一下：

在新增任何這三個元件之前，強烈建議你閱讀理念指南，以更好地理解這三個元件的設計。請注意，我們不能合併與我們的設計理念嚴重偏離的模型、排程器或 pipeline 新增，因為這會導致 API 不一致。如果你根本不同意某個設計選擇，請開啟一個反饋 issue，以便可以討論某個設計模式/設計選擇是否應在整個庫中更改，以及我們是否應更新我們的設計理念。整個庫的一致性對我們非常重要。

請確保在 PR 中新增指向原始程式碼庫/論文的連結，並最好直接在 PR 上 ping 原始作者，以便他們可以跟進進度並可能幫助解決問題。

如果你在 PR 中不確定或卡住了，不要猶豫留言尋求第一次審查或幫助。

Copied from 機制

在新增任何 pipeline、模型或排程器程式碼時，一個獨特而重要的要理解的特性是 `# 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.
    """

要了解更多，請閱讀這篇部落格文章的 `~不要~ 重複你自己*` 部分。

如何寫一個好的 issue

你的 issue 寫得越好，它被迅速解決的機會就越大。

  1. 確保你為你的 issue 使用了正確的模板。你可以選擇*錯誤報告*、*功能請求*、*關於 API 設計的反饋*、*新模型/pipeline/排程器新增*、*論壇*或一個空白 issue。在開啟一個新 issue時，請確保選擇正確的模板。
  2. 要精確：給你的 issue 一個合適的標題。儘量以最簡單的方式闡述你的 issue 描述。你提交 issue 時越精確，理解和可能解決問題所需的時間就越少。確保一個 issue 只針對一個問題，而不是多個問題。如果你發現了多個問題，只需開啟多個 issue。如果你的 issue 是一個 bug，儘量精確地說明是什麼 bug——你不應該只寫“diffusers 中的錯誤”。
  3. 可復現性：沒有可復現的程式碼片段 == 沒有解決方案。如果你遇到了一個 bug，維護者**必須能夠復現**它。確保你包含一個可以複製貼上到 Python 直譯器中以復現問題的程式碼片段。確保你的程式碼片段可以工作，*即*沒有缺失的匯入或缺失的影像連結等。你的 issue 應該包含一個錯誤訊息**和**一個可以無需任何更改即可複製貼上以復現完全相同的錯誤訊息的程式碼片段。如果你的 issue 使用了讀者無法訪問的本地模型權重或本地資料，那麼問題就無法解決。如果你不能分享你的資料或模型，請嘗試製作一個虛擬模型或虛擬資料。
  4. 簡約：儘量幫助讀者儘快理解問題，保持儘可能的簡潔。移除所有與問題無關的程式碼/資訊。如果你發現了一個 bug，試著建立一個最簡單的程式碼示例來演示你的問題，不要一發現 bug 就把你的整個工作流程都扔到 issue 裡。例如，如果你訓練一個模型並在訓練過程中的某個點出現錯誤，你應該首先嚐試理解是訓練程式碼的哪一部分導致了錯誤，並嘗試用幾行程式碼復現它。儘量使用虛擬資料而不是完整的資料集。
  5. 新增連結。如果你提到某個命名、方法或模型，請確保提供一個連結，以便讀者能更好地理解你的意思。如果你提到某個特定的 PR 或 issue，請確保將其連結到你的 issue 中。不要假設讀者知道你在說什麼。你在 issue 中新增的連結越多越好。
  6. 格式化。確保透過將程式碼格式化為 Python 程式碼語法，將錯誤訊息格式化為普通程式碼語法，來美化你的 issue。更多資訊，請參閱官方 GitHub 格式化文件。
  7. 請不要將您的問題看作是一個需要解決的工單，而應將其視為一本優秀百科全書中的一個優美條目。每一個新增的問題都是對公開知識庫的貢獻。透過提交一個撰寫精良的問題，您不僅能讓維護者更容易解決您的問題，還能幫助整個社群更好地理解該庫的某個方面。

如何編寫一個好的 PR

  1. 要像變色龍一樣。理解現有的設計模式和語法，並確保您新增的程式碼能夠無縫地融入現有程式碼庫。與現有設計模式或使用者介面有顯著差異的拉取請求將不會被合併。
  2. 要高度專注。一個拉取請求應該只解決一個問題。確保不要陷入“順便修復另一個問題”的陷阱。審查一次性解決多個不相關問題的拉取請求要困難得多。
  3. 如果可行，請嘗試新增一個程式碼片段，展示您所新增功能的使用示例。
  4. 您的拉取請求的標題應該是對其貢獻內容的總結。
  5. 如果您的拉取請求解決了某個 issue，請在拉取請求的描述中提及該 issue 的編號，以確保它們被關聯起來（這樣查閱該 issue 的人就會知道您正在處理它）；
  6. 要表明工作正在進行中，請在標題前加上 [WIP] 字首。這有助於避免重複工作，並將其與準備合併的 PR 區分開；
  7. 請嘗試按照如何編寫一個好的 issue 中說明的方式來組織和格式化您的文字。
  8. 確保現有測試能夠透過；
  9. 新增高覆蓋率的測試。沒有高質量的測試 = 不合並。
  • 如果您正在新增新的 @slow 測試，請確保它們能透過 RUN_SLOW=1 python -m pytest tests/test_my_new_model.py 命令。CircleCI 不會執行慢速測試，但 GitHub Actions 每晚都會執行！
  1. 所有公共方法都必須有資訊豐富的文件字串（docstrings），並且能與 markdown 很好地協同工作。請參閱 pipeline_latent_diffusion.py 作為示例。
  2. 由於程式碼庫的快速增長，確保不新增會顯著增加倉庫大小的檔案非常重要。這包括影像、影片和其他非文字檔案。我們傾向於利用 hf.co 上託管的 dataset，例如 hf-internal-testing 或 huggingface/documentation-images 來存放這些檔案。如果是外部貢獻，您可以隨意將影像新增到您的 PR 中，並請求 Hugging Face 成員將您的影像遷移到此資料集中。

如何提交 PR

在編寫程式碼之前，我們強烈建議您搜尋現有的 PR 或 issue，以確保沒有其他人已經在做同樣的事情。如果您不確定，最好先開一個 issue 來獲取一些反饋。

您需要具備基本的 git 技能才能為 🧨 Diffusers 做出貢獻。git 不是最容易使用的工具，但它有最好的手冊。在 shell 中輸入 git --help 並享受吧。如果您更喜歡書籍，Pro Git 是一個非常好的參考資料。

請按照以下步驟開始貢獻 (支援的 Python 版本)

  1. 透過點選倉庫頁面上的 ‘Fork’ 按鈕來複刻（fork）該倉庫。這會在您的 GitHub 使用者賬戶下建立一個程式碼副本。

  2. 將您的復刻克隆到本地磁碟，並將基礎倉庫新增為遠端倉庫

    $ git clone git@github.com:<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 分支上工作。

  1. 在虛擬環境中執行以下命令來設定開發環境

    $ pip install -e ".[dev]"

如果您已經克隆了倉庫，您可能需要執行 git pull 來獲取庫的最新更改。

  1. 在您的分支上開發新功能。

在您開發功能時，應確保測試套件能夠透過。您應像這樣執行受您更改影響的測試

$ 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

  1. 當您滿意後，請轉到您在 GitHub 上的復刻倉庫網頁。點選‘Pull request’，將您的更改傳送給專案維護者進行審查。

  2. 如果維護者要求您進行修改，這很正常。核心貢獻者也會遇到這種情況！為了讓每個人都能在拉取請求中看到更改，請在您的本地分支上工作，並將更改推送到您的復刻倉庫。它們會自動顯示在拉取請求中。

測試

我們提供了一個廣泛的測試套件來測試庫的行為和一些示例。庫的測試可以在 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 分支同步

為了避免 ping 上游倉庫（這會給每個上游 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 風格。

< > 在 GitHub 上更新

←可控生成 Diffusers 的道德準則→
© . This site is unofficial and not affiliated with Hugging Face, Inc.