如何为 Diffusers 🧨 做出贡献

如果您使用 AI 智能体进行贡献，请务必阅读AI 辅助与智能体贡献部分，了解我们的期望和准则。

我们 ❤️ 来自开源社区的贡献！欢迎所有人参与，我们珍视并感激各种形式的参与——不仅仅是代码。回答问题、帮助他人、主动联系以及改进文档，这些对社区都极具价值，所以如果你愿意，请大胆参与进来！

欢迎大家在公共 Discord 频道中打个招呼 👋。我们在这里讨论扩散模型的最新趋势、提问、分享个人项目、互相协助贡献，或者只是闲聊 ☕。

无论您选择以何种方式做出贡献，我们都致力于成为一个开放、包容且友善的社区。请阅读我们的行为准则，并在互动过程中注意遵守该准则。我们还建议您熟悉指导我们项目的道德准则，并请您遵循同样的透明与责任原则。

我们非常重视来自社区的反馈，因此，如果您认为自己的反馈有助于改进该库，请大胆提出——每一条消息、评论、issue 和 pull request (PR) 都会被阅读并予以考虑。

概述

您可以通过多种方式做出贡献，从在 issues 和 discussions 中回答问题，到为核心库添加新的扩散模型。

以下按所需时间投入从低到高，概述了不同的贡献方式。它们对社区都很有价值。

1. 在 GitHub Discussions 或 Discord 上提问和回答问题。
1. 在 GitHub Issues 选项卡上打开新的 issue。
1. 在 GitHub Issues 选项卡上回复问题。
1. 修复一个标记为“Good first issue”的简单问题，参见此处。
1. 为文档做出贡献。
1. 使用 Modular Diffusers 以远程代码的形式在 Hub 上发布流水线或模型。
1. 为 examples 做出贡献。
1. 解决一个难度稍高的问题，该问题带有“Good second issue”标签，参见此处。
1. 参与 Diffusers MVP 计划中的某个 issue。
1. 向库中添加新的 pipeline、model 或 scheduler。对于此类贡献，我们通常直接与模型作者合作；作为社区贡献者，请从 Hub（6）开始。请查看已打开的 “New Pipeline/Model” 和 “New scheduler” issue，并先阅读 Design Philosophy。

如前所述，所有贡献对社区都很有价值。接下来，我们将更详细地介绍每种贡献。

对于贡献 4 到 10（6 除外，因为它位于 Hub 上），你需要提交一个 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 issues 仅用于与 Diffusers 库直接相关的技术问题、错误报告、功能请求或关于库设计的反馈。

简而言之，这意味着所有与Diffusers 库代码（包括文档）无关的内容，都不应以 issue 的形式提出，而应通过GitHub Discussions或Discord进行提问。

在提交新问题之前，请考虑以下准则：

请确保在提交之前，您已在 GitHub 的 Issues 页面使用搜索栏查询过该问题是否已被提出。
请勿在另一个（相关的）issue 中报告新问题。如果另一个 issue 高度相关，请仍然打开一个新的 issue，并链接到该相关 issue。
请确保您的问题以英文撰写。
请检查将 Diffusers 更新到最新版本是否能解决您的问题。在提交问题之前，请确保 python -c "import diffusers; print(diffusers.__version__)" 的版本号高于或等于最新的 Diffusers 版本。
请记住，你在提交新问题时投入的精力越多，你获得回答的质量就越高，Diffusers 问题的整体质量也会越好。

新 issue 通常包含以下内容。

2.1. 可复现的最小化错误报告

Bug 报告应始终包含可复现的代码片段，并尽可能保持最小化和简洁。具体来说，这意味着：

尽可能缩小 bug 的范围，不要直接粘贴整个代码文件。
格式化您的代码。
请勿包含除 Diffusers 所依赖的外部库以外的任何外部库。
始终提供有关您环境的所有必要信息；为此，您可以在 shell 中运行 diffusers-cli env，并将显示的信息复制粘贴到 issue 中。
解释问题所在。如果读者不了解问题是什么以及它为何构成问题，（他/她）就无法解决它。
始终确保读者能够以最小的努力复现你的问题。如果你的代码片段因缺少库或未定义变量而无法运行，读者就无法帮助你。请确保你的可复现代码片段尽可能精简，并且可以直接复制粘贴到简单的 Python 控制台中运行。
如果需要模型和/或数据集才能复现您的问题，请确保读者能够访问该模型或数据集。您可以随时将模型或数据集上传到 Hub，以便轻松下载。请尽量保持模型和数据集尽可能小，以便尽可能轻松地复现您的问题。

有关更多信息，请参阅如何撰写好的 issue部分。

您可以在此处提交错误报告。

2.2. 功能请求

一个世界级的功能请求应涵盖以下要点：

首先说明动机：

这与库的某个问题或困扰有关吗？如果是，请解释原因。最好提供一段代码片段来演示该问题。
这与您在项目中需要的内容有关吗？我们非常乐意了解您的想法！
这是您参与开发并认为能够造福社区的项目吗？太棒了！请告诉我们它为您解决了什么问题。

撰写一个完整段落来描述该功能；
提供一个代码片段，展示其未来的用法；
如果这与某篇论文相关，请附上链接；
请附上您认为可能有帮助的任何附加信息（图纸、截图等）。

您可以在此处提交功能请求。

2.3 反馈

关于库设计的反馈，以及说明其设计优劣，对核心维护者构建用户友好的库大有裨益。要了解当前设计哲学背后的理念，请参阅此处。如果您认为某个设计选择与当前的设计哲学不符，请说明原因以及应如何修改。如果某个设计选择过于严格地遵循设计哲学，从而限制了使用场景，也请说明原因以及应如何修改。如果某个设计选择对您非常有用，也请留下备注，这对未来的设计决策是极佳的反馈。

您可以在此处提交反馈问题。

2.4 技术问题

技术问题主要涉及库中某些代码为何以特定方式编写，或某段代码的具体功能。请务必链接到相关代码，并详细说明为何该部分代码难以理解。

您可以在此处提交 issue 来咨询技术问题。

2.5 提议添加新的模型、调度器或流水线

如果扩散模型社区发布了您希望在 Diffusers 库中看到的新型模型、流水线或调度器，请提供以下信息：

扩散流水线、模型或调度器的简短描述，以及指向相关论文或公开发布版本的链接。
链接到其任意一个开源实现。
如果模型权重可用，请提供其链接。

另外，如果可以找到组件（模型、调度器、流水线等）的原作者，请记得通过其 GitHub 用户名对其进行标记。

如果您想自行将模型引入 Diffusers，请参阅在 Hub 上发布流水线或模型和添加流水线、模型和调度器。

您可以在此处提交模型/流水线/调度器的请求。

3. 在 GitHub issues 选项卡中回复问题

在 GitHub 上回复 issue 可能需要一些关于 Diffusers 的技术知识，但我们鼓励大家即使不能 100% 确定自己的回答是否正确，也尝试参与回答。以下是一些提供高质量 issue 回答的技巧：

尽可能简洁且精简。
请紧扣主题。针对该问题的回答应仅涉及该问题本身。
请提供代码、论文或其他来源的链接，以证明或支持您的观点。
以代码作答。如果一段简单的代码片段就是该问题的答案，或展示了如何解决问题，请提供一个完全可复现的代码片段。

此外，许多问题往往只是偏离主题、与其他问题重复或无关紧要。如果你能回复此类问题，鼓励提问者表述得更精确、提供重复问题的链接，或引导他们前往 GitHub Discussions 或 Discord，将对维护者大有裨益。

如果您已确认所提交的 bug 报告属实，且需要修改源代码，请查看以下章节。

对于除 6 之外的所有贡献，您都需要提交一个 PR。创建拉取请求部分将说明具体操作方法。

4. 解决一个“适合初学者的问题”

Good first issues 带有 Good first issue 标签。通常，issue 中已经说明了潜在解决方案应如何呈现，以便更容易修复。如果该 issue 尚未关闭，且你希望尝试修复它，只需留言“I would like to try this issue.”即可。通常有以下三种情况：

a.) 问题描述中已经提出了修复方案。在这种情况下，如果该方案对你来说合理，你可以提交一个 PR 或草稿 PR 来修复它。
b.) 问题描述中未提出修复方案。在这种情况下，请在该问题的评论中自行提出修复方案。用几句话描述思路即可。在提交 PR 之前，请等待 Diffusers 团队成员确认。
c.) 已经有一个未合并的 PR 旨在修复该问题，但 issue 尚未关闭。如果该 PR 已长期未更新（stale），你可以直接提交一个新的 PR，并在其中链接到那个过时的 PR。PR 经常会出现这种情况，因为最初想要修复该问题的贡献者可能突然抽不出时间继续推进。这在开源社区中非常常见，属于正常现象。在这种情况下，如果你愿意重新尝试并借鉴现有 PR 中的经验，社区会非常欢迎。如果已经存在一个 PR 且仍在活跃维护中，你可以通过提出建议、审查该 PR，甚至询问是否可以参与该 PR 的贡献来帮助作者。

5. 为文档做出贡献

一个优秀的库总是拥有出色的文档！官方文档通常是新用户接触该库的第一个入口，因此为文档做出贡献是一项极具价值的贡献。

为库做出贡献可以有多种形式：

修正拼写或语法错误。
修正文档字符串中不正确的格式。如果您发现官方文档显示异常或链接失效，我们非常欢迎您花些时间进行修正。
修正文档字符串中输入或输出张量的形状或维度。
澄清难以理解或不正确的文档。
更新过时的代码示例。
将文档翻译成其他语言。

在Diffusers 官方文档页面上显示的任何内容均属于官方文档的一部分，可在相应的文档源中进行更正或调整。

请查看此页面，了解如何在本地验证对文档所做的更改。

6. 在 Hub 上发布流水线或模型

借助 Modular Diffusers，流水线可以作为远程代码存在于任何 Hub 仓库中。任何人都可以使用 from_pretrained(..., trust_remote_code=True) 加载它，而无需等待 Diffusers 发布新版本。如果你是社区贡献者，正在引入新的流水线或模型，请从这里开始。请参阅自定义块以发布流水线，请参阅自定义模型以发布模型。

请在对应的模型请求下告知我们（如果没有，请新建一个）：我们会对实现提供反馈，并将我们喜欢的作品收录到我们的 Community Modular Diffusers Blocks 集合中。随后，我们将决定如何在库中支持该模型：我们可能会将您的版本合并到上游，与作者合作开发官方版本，或者直接将用户引导至您的版本。也请告诉我们您在过程中遇到的任何阻碍：令人困惑的 API、缺失的文档、Bug 等。这些反馈对我们来说与 pipeline 本身同样重要。

7. 贡献训练示例

Diffusers 示例是一组位于 examples 中的训练脚本。

我们支持两种类型的训练示例：

官方训练示例
研究训练示例

研究训练示例位于 examples/research_projects，而官方训练示例包括 examples 下的所有文件夹，但不包括 research_projects 和 community 文件夹。官方训练示例由 Diffusers 的核心维护者维护，而研究训练示例则由社区维护。这与该库在 Hub 上同时保留少量官方流水线（pipelines）和社区流水线的原因相同：核心维护者无法维护扩散模型的所有可能训练方法。如果 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 library，因为它与 Diffusers 深度集成。当示例脚本可以正常运行后，请务必添加一份详尽的 README.md，准确说明如何使用该示例。此 README 应包含：

一个示例命令，演示如何运行如此处所示的示例脚本。
指向一些训练结果（日志、模型等）的链接，展示用户预期能达到的效果，如此处所示。
如果您正在添加一个非官方/研究性质的训练示例，请别忘了添加一句说明，表明您正在维护该训练示例，并附上您的 git 用户名，如此处所示。

如果您正在为官方训练示例做出贡献，请确保在其文件夹中添加一个测试，例如 examples/dreambooth/test_dreambooth.py。对于非官方训练示例，则无需这样做。

8. 修复“适合第二项任务”

适合第二次的任务会标记为 Good second issue 标签。它们通常比适合第一次的任务更复杂，描述中提供的修复指引较少，并且需要对库有相当程度的理解。

如果你对解决一个不错的二级问题感兴趣，请在评论中用几句话分享你对该问题的看法以及你计划采用的方法，并在提交 PR 之前获得维护者的确认。如果该问题已经有人提交了 PR 但未被合并，请先查看并了解原因，然后再提出新的方案。

9. 认领 Diffusers MVP 问题

Diffusers MVP 计划列出了我们最希望获得帮助的议题。它们类似于“适合第二项贡献的议题”，但难度更高、耗时更长，该计划会奖励接手这些议题的贡献者。在提交 PR 之前，请先以评论的形式分享你的思路，并等待维护者的确认。该计划还设有创意赛道：用几句话告诉我们一个能提升 Diffusers 影响力的想法，无需包含实现细节。

10. 添加流水线、模型和调度器

如果您是模型的作者，请联系我们以便与您协调集成事宜：请提交一个功能请求，或者如果已有相关请求，请留下评论。

如果您是社区贡献者，请先从 Hub 仓库开始，参见在 Hub 上发布流水线或模型，并在功能请求下告知我们您有兴趣将其上游化。

Pipelines、models 和 schedulers 是 Diffusers 库中最核心的组件。它们提供了对前沿扩散技术的便捷访问，从而使社区能够构建功能强大的生成式 AI 应用。

通过添加新的模型、流水线或调度器，您可能会为任何依赖 Diffusers 的用户界面启用一种强大的新用例，这对整个生成式 AI 生态系统都具有巨大的价值。

当发布新的模型或流水线支持时

如果您提前与 Diffusers 团队协调集成工作，新的模型或流水线可能会被纳入某个版本。请随时通过 Diffusers 仓库中的 issue 或发送邮件至 [email protected] 与我们联系。

模型或流水线拉取请求合并后，不会自动触发版本发布。在发布之前，维护者会先确认集成已完成，并且发布测试通过。

对新模型或流水线的支持通常会在下一个次要版本中发布。集成代码会合并到 main 分支，并基于该分支创建发布分支。该发布版本包含自上一个版本以来合并的所有更改，而不仅仅是模型或流水线的集成。

发布说明会突出介绍新的模型或流水线，并总结该版本中包含的其他更改。补丁版本通常仅用于修复现有版本中的问题。

Diffusers 针对所有三个组件都有一些开放的功能请求——如果您还不确定想要添加哪个具体组件，可以随意浏览一下：

在添加上述三个组件中的任何一个之前，强烈建议您先阅读设计哲学指南，以便更好地理解这三个组件的设计。请注意，如果模型、调度器或流水线的添加内容与我们的设计哲学存在重大偏差，我们将无法合并，因为这会导致 API 不一致。如果您从根本上不同意某项设计决策，请改为提交一个反馈问题，以便讨论是否应在整个库中更改特定的设计模式/设计决策，以及我们是否应更新设计哲学。库内的一致性对我们非常重要。

请务必在 PR 中添加指向原始代码库/论文的链接，并最好直接在 PR 中 @ 原始作者，以便他们能够跟进进展，并可能协助解答相关问题。

如果您对 PR 感到不确定或卡住了，请随时留言请求初步审查或帮助。

Copied from mechanism

在添加任何 pipeline、model 或 scheduler 代码时，需要理解一个独特且重要的特性，即 # 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

问题描述得越清晰，越有可能被快速解决。

请确保你针对该问题使用了正确的模板。你可以选择 Bug Report、Feature Request、Feedback about API Design、New model/pipeline/scheduler addition 或空白问题。在打开 a new issue 时，请务必选择正确的模板。使用类问题应发布在 GitHub Discussions 中，而不是作为 issue 提交。
表述精确：为你的问题起一个贴切的标题。尽量用简洁的语言描述问题。提交问题时表述得越精确，理解并解决该问题所需的时间就越短。请确保每个 issue 只针对一个问题，不要将多个问题混在一起。如果你发现了多个问题，请分别提交多个 issue。如果你的问题是 bug，请尽可能精确地说明具体是什么 bug——不要只写“diffusers 中出现错误”。
可复现性：没有可复现的代码片段就等于没有解决方案。如果您遇到 bug，维护者必须能够复现该问题。请确保您包含一段可以复制粘贴到 Python 解释器中运行以复现问题的代码片段。请确保您的代码片段可以正常运行，即没有缺失的导入或指向图像的缺失链接等。您的 issue 应包含错误消息以及一段无需任何修改即可复制粘贴并复现完全相同错误消息的代码片段。如果您的 issue 使用了读者无法访问的本地模型权重或本地数据，则该 issue 无法解决。如果您无法共享您的数据或模型，请尝试创建一个虚拟模型或虚拟数据。
极简主义：在尽可能简洁的前提下，帮助读者尽快理解问题。删除所有与问题无关的代码和信息。如果发现了一个 bug，请尝试编写最简单的代码示例来复现该问题，而不是在发现 bug 后就将整个工作流直接粘贴到 issue 中。例如，如果你在训练模型时在某处遇到错误，应首先尝试确定是哪部分训练代码导致了该错误，并尝试用几行代码来复现它。请尽量使用虚拟数据，而不是完整的数据集。
背景：请告诉我们，在遇到该 bug 或需要该功能时，你正在做什么工作，例如基于 Diffusers 构建的应用、研究项目，或你运行用于在库中查找 bug 的智能体。一两句话即可，附上项目链接更佳。我们收到的 issue 和 PR 数量远超当前处理能力，因此背景信息有助于我们根据影响程度进行优先级排序。
添加链接。如果你指的是某个特定的命名、方法或模型，请确保提供链接，以便读者更好地理解你的意思。如果你指的是某个具体的 PR 或 issue，请确保将其链接到你的 issue。不要假设读者知道你在说什么。你在 issue 中添加的链接越多越好。
格式规范。请妥善格式化你的 issue，将代码格式化为 Python 代码语法，将错误信息格式化为普通代码语法。有关更多信息，请参阅 GitHub 官方格式文档。
请将你的问题视为一部精心撰写的百科全书中一个精彩的条目，而非一张待解决的工单。每一个新增的问题都是对公开知识体系的贡献。撰写一份条理清晰的问题报告，不仅能让维护者更轻松地解决你的问题，也有助于整个社区更好地理解该库的某个特定方面。

如何撰写一份优质的 PR

请始终从 issue 开始。找到你的 pull request 所解决的 issue，或者如果还没有人提出，就自己开一个，并在编写代码之前给维护者留出回应的时间。对我们来说效果最好的工作流程是：先开一个 issue，然后讨论解决方案，最后基于该讨论提交 PR。这让我们能够将时间集中在影响最大的 issue 上，在代码出现之前就就范围达成一致，并避免重复劳动。请在 PR 描述中提及 issue 编号（例如 Fixes #1234），以便将两者关联起来。
像变色龙一样。理解现有的设计模式和语法，确保你新增的代码能够无缝融入现有代码库。与现有设计模式或用户界面存在显著差异的 Pull Request 将不会被合并。
保持专注。一个拉取请求（pull request）应只解决一个问题，且仅解决该问题。请避免陷入“既然在添加功能，顺便也修复另一个问题”的陷阱。同时解决多个不相关问题的拉取请求会大大增加代码审查的难度。
修复模式，而非孤例。一个问题可能横跨多个文件：如果同一个 bug 在代码库中反复出现，请搜索所有实例，并在一个 PR 中全部修复，同时明确且系统地界定范围（例如“修复所有调度器中的可变默认值”），而不是为每个实例单独提交一个 PR。
您的拉取请求（pull request）标题应是对该贡献的摘要。若要表示工作正在进行中，请在标题前加上 [WIP] 前缀；这样可以避免重复劳动，并将该 PR 与已准备好合并的 PR 区分开来。
请按照如何撰写高质量的 issue中的说明，尝试组织并格式化你的文本。
在提交 PR 之前，请先自行审查你的 diff。像评审者一样阅读它，并修复你发现的问题。我们强烈建议运行 self-review 技能：它会执行与 @claude CI 评审者相同的评分标准。按照使用 AI 智能体进行编码中的说明配置你的智能体，并遵循 AI 辅助和智能体贡献。在描述中说明你有意保留未改动的发现，以便评审者知道这是你的决定，而非疏忽。
确保现有测试通过。
添加高覆盖率的测试。没有质量测试 = 不予合并。

如果您正在添加新的 @slow 测试，请确保使用 RUN_SLOW=1 python -m pytest tests/test_my_new_model.py 时它们能够通过。 CircleCI 不会运行慢速测试，但 GitHub Actions 每晚都会运行！

所有公共方法都必须包含信息丰富的文档字符串，并且能够很好地与 Markdown 配合使用。示例请参见 pipeline_latent_diffusion.py。
由于仓库正在快速增长，确保不会添加任何会显著增加仓库体积的文件至关重要。这包括图像、视频以及其他非文本文件。我们倾向于使用由 hf.co 托管的 dataset（例如 hf-internal-testing 或 huggingface/documentation-images）来存放这些文件。如果是外部贡献，您可以将图像添加到您的 PR 中，并请求 Hugging Face 成员将您的图像迁移到该数据集。

如何提交 PR

在编写代码之前，我们强烈建议您先搜索现有的 PR 或 issue，以确认是否已有人正在处理相同的问题。如果您不确定，最好先提交一个 issue 来获取一些反馈。

要参与 🧨 Diffusers 的贡献，你需要具备基本的 git 技能。git 并不是最容易上手的工具，但它拥有最出色的手册。在终端中输入 git --help 即可开始探索。如果你更喜欢书籍，Pro Git 是一本非常优秀的参考书。

按照以下步骤开始贡献（支持的 Python 版本）：

点击仓库页面上的“Fork”按钮，fork 该仓库。这会在你的 GitHub 用户账户下创建一份代码副本。

将您的 fork 克隆到本地磁盘，并将基础仓库添加为远程仓库：

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

创建一个新分支来保存你的开发更改：
```
$ git checkout -b a-descriptive-name-for-my-changes
```

请勿在 main 分支上工作。

在虚拟环境中运行以下命令来设置开发环境：
```
$ pip install -e ".[dev]"
```

如果您已经克隆了该仓库，可能需要执行 git pull 以获取该库的最新更改。

在您的分支上开发功能。

在开发功能时，请确保测试套件通过。您应该以如下方式运行受您更改影响的测试：

$ 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

一旦您确认无误，请前往您在 GitHub 上 fork 的仓库网页。点击“Pull request”，将您的更改发送给项目维护者进行审查。
维护者要求你进行修改是很正常的，核心贡献者也会遇到这种情况！为了让所有人都能在 Pull request 中看到这些更改，请在你的本地分支上工作，并将更改推送到你的 fork。这些更改会自动出现在 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

将 fork 的 main 分支与上游（HuggingFace）main 分支同步

为避免向上游仓库发送 ping（这会在每个上游 PR 中添加引用备注，并向参与这些 PR 的开发者发送不必要的通知），在同步 fork 仓库的主分支时，请遵循以下步骤：

在可能的情况下，避免通过分支和 PR 在 fork 仓库中与上游同步。相反，应直接合并到 fork 的 main 分支。
如果确实需要提交 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/ 中，同时以智能体插件的形式发布，以便按需任务技能能够一步安装。

对贡献者只读 — .ai/ 由核心维护者管理。请勿在您的 PR 中编辑 .ai/ 下的文件（或根目录下的 AGENTS.md / CLAUDE.md 符号链接，或已安装的 .agents/skills / .claude/skills）。如果您发现内容缺失或错误，请提交 issue 或在 PR 中指出，维护者会进行更新。
Guidelines — .ai/AGENTS.md 通过根目录下的 AGENTS.md / CLAUDE.md 符号链接加载到每个 agent 会话中； .ai/references/ 下的参考指南会在跟随链接时按需读取：
- .ai/AGENTS.md — 顶层编码规范
- .ai/references/models.md — 注意力模式、模型实现规则、通用约定
- .ai/references/pipelines.md — 流水线约定
- .ai/references/modular.md — 模块化流水线约定与转换检查清单
- .ai/references/testing.md — 必需的测试层级、测试器混入、dummy-component 规则
- .ai/references/review-rules.md — 评审人员关注的要点
Skills (under .ai/skills/, ，按需加载以处理特定任务）：
- model-integration — 端到端地将新模型或流水线添加到 diffusers（文件结构、集成检查清单、测试布局、权重转换）
- self-review — 在提交 PR 之前，根据项目规则审查你的更改
- diffusers-cli — 在终端中运行流水线并检查架构
- custom-blocks — 将 ModularPipelineBlocks 子类打包到 Hub

无论您选择哪种方式，在开始之前，请先让您的智能体确认其自身的配置——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，而不是为每个单独实例提交多个 issue 或 PR。
在提交前进行自查。 运行 self-review 技能——它会依据 .ai/references/review-rules.md 审查你的 diff，该文件与 @claude CI 审查员使用的标准一致——并处理其报告的问题。该技能只是一个辅助工具，并非权威，也可能出错。请重点关注那些你认为合理的阻塞性问题，并尽可能清理无用/未使用的代码。如果你不同意某条建议，可以将其留给审查员在 PR 打开后讨论——你分享的备注（见下文）会告知审查员这是你有意为之的决定。
分享你的自查笔记。请在 PR 中发布最终的自查报告——即反映你所提交 diff 的那一轮——将其放在描述中或作为评论，并包含你有意未修复的问题及其原因。这有助于审阅者了解哪些内容已经检查过、哪些决定是有意为之，通常也能省去几轮来回沟通。
保持 PR 沟通简洁。 审查者在你的 PR 中阅读的所有内容——描述、提交信息、评论和回复、代码注释——都必须让人类易于理解。如果是由你的 agent 起草的，不要只是粗略浏览。请仔细阅读，并要求 agent 修改，直到内容合理、简洁，且是你自己会写出的风格。你是你所发布的所有内容的作者。
Include in the PR description:
- 指向维护者已确认该工作的 issue 或讨论的协调链接。
- 你运行的 测试命令 及其结果（请粘贴相关输出，而不仅仅是“测试通过”）。
- 如上所述，您的自我审查笔记（或包含这些笔记的 PR 评论链接）。

如果您是模型作者，或属于官方维护某个模型的团队，我们鼓励您使用智能体来完成新模型的集成。请遵循该仓库的推荐配置，并使用model-integration技能。在提交 PR 之前，请先与维护者协调好范围——参见添加流水线、模型和调度器。

Update on GitHub