Diffusers 贡献指南从提问答疑到新增 Pipeline 模型的完整参与路线【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers本指南基于 Diffusers 官方贡献文档系统梳理了从社区问答、提交 Issue、撰写高质量 PR到构建社区 Pipeline、添加训练示例、乃至新增模型/调度器/流水线的完整贡献路径。读完本文你将掌握 Diffusers 的代码组织方式Pipeline / Model / Scheduler 三类组件、# Copied from复制机制、开发环境搭建与测试命令能够独立完成一次从 Fork 到合并的完整开源贡献。概述九种贡献方式 Diffusers 对来自开源社区的贡献持完全开放态度且所有类型的贡献都受到重视——不仅仅是代码。回答问题、帮助他人、主动交流以及改进文档对社区的价值与提交代码同等重要。下面按难度升序列出九种贡献方式49 类需要提交 PR级别贡献方式说明1在论坛或 Discord 提问/解答零门槛构建公共知识库2提交新 Issue / 发起讨论反馈 bug、功能请求、设计反馈3解答已有 Issue需要一定的库知识4修复 Good first issue入门级代码贡献Issue 通常附有解决建议5文档贡献修正拼写、修复 docstring、翻译文档6贡献社区 Pipeline在DiffusionPipeline基础上构建自定义流程7完善训练示例官方示例或研究型示例8处理 Good second issue中等难度需要较深理解9添加新 Pipeline / 模型 / 调度器最高难度需先阅读设计哲学在动手之前建议先阅读 设计哲学理解 Pipeline、模型、调度器三类组件的设计理念——如果新增组件与设计理念严重分歧将无法被合并。1. 在讨论区提问与解答构建高质量公共知识与 Diffusers 相关的任何问题都可以发布在官方论坛或 Discord 频道包括训练/推理实验报告、个人项目展示、论文解读、基于 Diffusers 的项目求助、关于扩散模型的伦理讨论等。一个关键原则是提问/回答投入的精力越多产生的公共知识质量就越高。高质量的问题或回答应具备精确性、简洁性、相关性、易于理解、可访问性和格式规范等特质。低质量的问题会拉低整个公共知识库的质量。关于渠道选择论坛内容能被搜索引擎更好地收录帖子按热度排序、便于查找历史问答也更容易被直接链接引用而 Discord 是即时聊天模式适合快速交流但信息会随时间淹没。因此建议在论坛发布优质问答若 Discord 讨论产生了有价值的结论应整理后发布到论坛以惠及更多读者。2. 提交新 Issue五类模板的使用准则GitHub Issue 仅限处理与 Diffusers 库代码含文档直接相关的技术问题无关内容应发布到论坛或 Discord。提交新 Issue 前应确认先用搜索栏确认没有重复的 Issue请勿在现有 Issue 下追加新问题应新建议题并关联相关链接使用英文提交提交前确认版本python -c import diffusers; print(diffusers.__version__)显示的版本号不低于最新版本。新 Issue 通常分为以下几类2.1 可复现的最小化错误报告不要直接粘贴整个代码文件尽量缩小问题范围规范代码格式除 Diffusers 依赖库外不包含其他外部库务必提供环境信息在终端运行diffusers-cli env将输出复制到 Issue 中。该命令由 src/diffusers/commands/env.py 中的EnvironmentCommand实现会收集 Python 版本、PyTorch 版本、diffusers 版本、CUDA 信息等关键环境数据详细说明问题及其影响确保代码片段可复现——不能因缺少库或未定义变量而无法运行应精简到可直接复制到 Python shell 运行如需特定模型/数据集请确保读者能获取可上传至 Hub并尽量保持体积最小。2.2 功能请求优质的功能请求应包含动机说明是否与库的使用痛点相关、是否因项目需求产生、是否是你已实现的功能、用完整段落描述功能特性、提供代码片段演示预期用法、论文链接如涉及、辅助材料示意图、截图等。2.3 设计反馈关于库设计的反馈正面或负面都能帮助核心维护者打造更友好的库。若某个设计选择与当前理念不符请说明原因及改进建议若某个设计对您特别实用也请留下备注——这对未来的设计决策极具参考价值。可参照 设计哲学 了解当前设计理念。2.4 技术问题主要涉及库代码的实现逻辑或特定功能模块的作用。提问时务必附上相关代码链接并详细说明难以理解的具体原因。2.5 新模型/调度器/Pipeline 提案若扩散模型社区发布了希望集成到 Diffusers 的新模型、Pipeline 或调度器请提供简要说明及论文或发布链接、开源实现链接如有、模型权重下载链接如已公开。若愿意参与开发请告知维护者以便指导并尝试通过 GitHub 账号标记原始组件作者。3. 解答已有 Issue回答 GitHub Issue 需要一定的 Diffusers 技术知识但鼓励所有人尝试参与——即使答案不完全正确。高质量回答的建议保持简洁精炼、严格聚焦问题本身、提供代码/论文等佐证材料、优先用代码说话——若代码片段能解决问题请提供完整可复现代码。面对离题、重复或无关的问题可以通过以下方式协助维护者引导提问者精确描述问题、标记重复 Issue 并附原链接、推荐用户至论坛或 Discord。4. 修复 Good first issue标有 Good first issue 标签的问题通常已说明解决方案建议。若该问题尚未关闭且想尝试解决只需留言我想尝试解决这个问题。通常有三种情况a.) 问题描述已提出解决方案——认可方案即可直接提交 PR 或草稿 PRb.) 问题描述未提出解决方案——可询问修复建议Diffusers 团队会尽快回复c.) 已有 PR 但问题未关闭——若原 PR 停滞可新开 PR 并关联原 PR若原 PR 仍活跃可通过建议、审查或协作等方式帮助原作者。5. 文档贡献优秀库必然拥有优秀文档文档是新用户的首要接触点。贡献形式包括修正拼写/语法错误、修复 docstring 格式错误如显示异常或链接失效、修正 docstring 中张量的形状/维度描述、优化晦涩或错误的说明、更新过时代码示例、文档翻译。官方文档源文件位于 docs/source 目录其中 docs/source/zh 为简体中文翻译包含本贡献指南及设计哲学等概念文档。修改文档前请查阅 docs 目录 下的验证说明。6. 贡献社区 Pipeline从零构建一个单步 Pipeline社区 Pipeline 是基于 [DiffusionPipeline] 的自定义流程任何人都能通过设置custom_pipeline参数加载使用。与 GitHub Pipeline 相比Hub Pipeline 完全可定制调度器、模型、pipeline 代码均可自定义而 GitHub Pipeline 仅限于自定义 pipeline 代码。GitHub Pipeline 需要提交 PR 经过 Diffusers 团队审查较慢Hub Pipeline 可直接上传无需审查最快。关于设立社区 Pipeline 的原因可参考 Issue #841——核心维护者无法维护 diffusion 模型所有可能的推理使用方式但也不希望限制社区构建这些流程。[!TIP] 社区 Pipeline 与官方 Pipeline 的加载方式、GitHub 与 Hub 两种托管方式的详细区别可参阅 Community pipelines and components。下面演示如何创建一个简单的单步流程——UNet 仅执行单次前向传播并调用调度器一次。该示例在仓库中真实存在examples/community/one_step_unet.py。第 1 步创建 Pipeline 类并注册组件创建one_step_unet.py文件。该文件可包含任意所需包只要用户已安装但确保仅有一个继承自DiffusionPipeline的流程类。在__init__中添加 UNet 和调度器并通过register_modules注册——这是确保流程及其组件可通过 [~DiffusionPipeline.save_pretrained] 保存的关键from diffusers import DiffusionPipeline import torch class UnetSchedulerOneForwardPipeline(DiffusionPipeline): def __init__(self, unet, scheduler): super().__init__() self.register_modules(unetunet, schedulerscheduler)register_modules是DiffusionPipeline的底层方法定义于 src/diffusers/pipelines/pipeline_utils.py 的register_modules方法它会把传入的组件注册为 pipeline 的属性并记录在model_index.json中从而支持save_pretrained/from_pretrained的完整序列化闭环。第 2 步实现__call__前向逻辑在前向传播中可添加任意功能。对于单步流程创建随机图像并通过设置timestep1调用 UNet 和调度器一次from diffusers import DiffusionPipeline import torch class UnetSchedulerOneForwardPipeline(DiffusionPipeline): def __init__(self, unet, scheduler): super().__init__() self.register_modules(unetunet, schedulerscheduler) 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注意这里直接读取了self.unet.config.in_channels和self.unet.config.sample_size——这是 Diffusers 模型配置系统的典型用法模型通过ConfigMixin暴露配置pipeline 代码据此动态构造输入张量形状无需硬编码尺寸。第 3 步运行 Pipeline现在可以通过传入 UNet 和调度器来运行流程若流程结构相同也可加载预训练权重from diffusers import DDPMScheduler, UNet2DModel scheduler DDPMScheduler() unet UNet2DModel() pipeline UnetSchedulerOneForwardPipeline(unetunet, schedulerscheduler) output pipeline() # 加载预训练权重 pipeline UnetSchedulerOneForwardPipeline.from_pretrained(google/ddpm-cifar10-32, use_safetensorsTrue) output pipeline()第 4 步选择分享方式GitHub Pipeline通过向 Diffusers 仓库提交拉取请求将one_step_unet.py添加到 examples/community 子文件夹中Hub Pipeline在 Hub 上创建模型仓库并上传one_step_unet.py文件。examples/community 目录目前收录了大量社区 Pipeline覆盖了文本到图像、图像到图像、修复、ControlNet、LoRA 加载、视频生成等丰富场景如lpw_stable_diffusion.py、pipeline_flux_with_cfg.py、pipeline_stg_wan.py等是学习社区 Pipeline 写法的绝佳素材库。7. 贡献训练示例训练示例位于 examples 目录分为两类官方训练示例examples目录下除research_projects和community外的所有文件夹由 Diffusers 核心维护者维护研究型训练示例examples/research_projects 目录由社区维护。这与官方 Pipeline 与社区 Pipeline 的区分原因相同核心维护者不可能维护 diffusion 模型所有可能的训练方法。若某种训练范式过于实验性或不够普及相应训练代码应放入research_projects并由作者维护。目录结构规范每个示例目录包含一个或多个训练脚本、requirements.txt和README.md。用户使用时需要先克隆代码库git clone https://github.com/huggingface/diffusers并安装训练所需的所有额外依赖cd diffusers pip install -e .[dev] pip install -r examples/your-example-folder/requirements.txt因此requirements.txt应定义训练示例所需的所有 pip 依赖。可参考 examples/dreambooth/requirements.txt——它声明了accelerate0.16.0、torchvision、transformers4.25.1、ftfy、tensorboard、Jinja2、peft0.7.0等依赖。脚本编写要求运行示例所需的所有代码应集中在单个 Python 文件中用户应能通过命令行python your-example.py --args直接运行示例应保持简洁目的是复现已知训练方案而非创造最先进的模型避免添加过多自定义逻辑——因此这些示例也是优质的教学材料强烈建议使用 Accelerate 库它与 Diffusers 深度集成提交前参考现有示例如 examples/dreambooth/train_dreambooth.py了解规范格式。README 要求运行示例的具体命令训练结果链接日志/模型等展示用户可预期的效果若添加非官方/研究性训练示例必须注明维护者信息含 Git 账号格式可参考 examples/research_projects/intel_opts 目录下的说明贡献官方训练示例时还需在对应目录添加测试文件如 examples/dreambooth/test_dreambooth.py非官方示例无需此步骤。8. 处理 Good second issue标有 Good second issue 标签的问题通常比 Good first issue 更复杂描述一般不会提供详细解决指引需要贡献者对库有较深理解。若想解决此类问题可直接提交 PR 并关联对应 Issue。若已有未合并的 PR请分析原因后提交改进版。注意此类 PR 的合并难度通常更高需要帮助时请大胆向核心维护者询问。9. 添加 Pipeline、模型和调度器Pipeline、模型和调度器是 Diffusers 库最重要的组成部分。添加新组件可能为依赖 Diffusers 的任何用户界面开启全新的用例。仓库中这三类组件的源码位置Pipelinesrc/diffusers/pipelines模型src/diffusers/models调度器src/diffusers/schedulers在动手之前强烈建议阅读设计哲学理解三类组件的设计理念。若新增组件与设计理念严重分歧将无法合并因为会导致 API 不一致。若从根本上不同意某个设计选择应提交设计反馈 Issue 讨论。请确保在 PR 中添加原始代码库/论文的链接并最好直接 原始作者以便他们跟踪进展并提供帮助。若在 PR 过程中遇到不确定的情况随时留言请求初步审查。# Copied from复制机制在添加任何 Pipeline、模型或调度器代码时理解# Copied from机制是独特且重要的。整个 Diffusers 代码库大量使用该机制其目的是保持代码库易于理解和维护用# Copied from标记的代码必须与复制来源的代码完全相同。这样每当运行make fix-copies时就可以轻松更新并将更改传播到多个文件。例如下面的AltDiffusionPipelineOutput使用# Copied from机制复制StableDiffusionPipelineOutput唯一的区别是将类前缀从Stable改为Alt# 从 diffusers.pipelines.stable_diffusion.pipeline_output.StableDiffusionPipelineOutput 复制并将 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. 从源码看该机制的底层实现位于 utils/check_copies.py脚本通过正则_re_copy_warning匹配# Copied from diffusers.模块.对象注释用find_code_in_diffusers定位原始对象在src/diffusers下的定义代码支持OldName-NewName替换模式并对复制代码运行ruff格式化后与现有代码比对make fix-copies则调用check_copies.py --fix_and_overwrite自动同步差异。同时Makefile 中的make style和make fixup目标也会触发repo-consistency检查包括check_dummies.py、check_repo.py、check_inits.py确保复制代码与原始代码保持一致。如何撰写优质 Issue问题描述越清晰被快速解决的可能性就越高。选择正确的模板错误报告、功能请求、API 设计反馈、新模型/Pipeline/调度器添加等在新建 Issue 时务必选择正确模板精确描述为 Issue 起恰当的标题用最简练的语言描述问题。确保一个 Issue 只针对一个问题错误报告应精确描述错误类型不应只写diffusers 出错可复现性无法复现的代码片段 无法解决问题。确保包含可复制粘贴到 Python 解释器的代码片段没有缺少导入或图片链接等问题。若涉及本地权重或数据请尝试创建虚拟模型或虚拟数据最小化原则删除所有与问题无关的代码/信息。发现错误时创建最简单的代码示例不要转储整个工作流程。训练报错时应先定位是哪部分代码导致用模拟数据替代完整数据集测试添加引用链接提及特定命名、方法或模型时务必提供引用链接不要假设读者了解你所指内容规范格式Python 代码使用代码语法块错误信息使用标准代码语法将 Issue 视为百科全书的精美词条每个规范撰写的 Issue 不仅是向维护者传递问题的途径更是帮助社区深入理解库特性的公共知识贡献。优质 PR 编写规范保持风格统一理解现有设计模式和语法规范显著偏离现有设计模式或用户界面的 PR 将不予合并聚焦单一问题每个 PR 只解决一个明确问题避免顺手修复其他问题——包含多个无关修改的 PR 会极大增加审查难度如适用添加代码片段演示新增功能的使用方法PR 标题应准确概括其核心贡献若 PR 针对某个 Issue请在描述中注明 Issue 编号以建立关联进行中的 PR 请在标题添加[WIP]前缀文本表述与格式要求参照优质 Issue 编写规范确保现有测试用例全部通过必须添加高覆盖率测试未经充分测试的代码不予合并。若新增slow测试请使用RUN_SLOW1 python -m pytest tests/test_my_new_model.py确保通过CircleCI 不执行慢速测试但 GitHub Actions 每日夜间运行所有公开方法必须包含格式规范、兼容 markdown 的 docstring避免增加仓库体积不要添加图片、视频等非文本文件。建议优先使用托管在 hf.co 的 dataset 存放这类文件外部贡献者可将图片加入 PR 并请 Hugging Face 成员迁移至该数据集。提交 PR 流程编写代码前强烈建议先搜索现有 PR 或 Issue 确认没有重复工作如有疑问建议先创建 Issue 获取反馈。贡献需要基本的git技能——在终端输入git --help即可查阅手册。按以下步骤操作1. Fork 与克隆在仓库页面点击 Fork 按钮创建代码副本至你的 GitHub 账户然后克隆 fork 并添加主仓库为远程源$ git clone gitgithub.com:您的GitHub账号/diffusers.git $ cd diffusers $ git remote add upstream https://github.com/huggingface/diffusers.git2. 创建开发分支$ git checkout -b 您的开发分支名称禁止直接在main分支上修改。3. 配置开发环境$ pip install -e .[dev]若已克隆仓库可能需要先执行git pull获取最新代码。4. 开发并确保测试通过运行受影响测试$ pip install -e .[test] $ pytest tests/待测文件.py也可运行完整测试套件需高性能机器$ make test5. 格式化与质量检查 Diffusers 使用black和isort保持代码风格统一并在此基础上使用ruff和自定义脚本检查代码错误。修改后请执行$ make style以及手动运行与 CI 相同的质量检查$ make quality从 Makefile 的源码可以看出make style会执行ruff check --fix、ruff format、doc-builder style、自动生成代码autogenerate_code和额外风格检查extra_style_checks包括custom_init_isort.py与check_doc_toc.py --fix_and_overwrite而make quality则以只读方式运行ruff check、ruff format --check、doc-builder style --check_only、check_doc_toc.py和check_ai.py验证仓库是否处于良好状态。6. 提交与推送$ git add modified_file.py $ git commit -m 关于您所做更改的描述性信息。 $ git pull upstream main # 定期同步上游变更 $ git push -u origin 此处替换为您的描述性分支名称7. 发起 Pull Request确认无误后访问你 GitHub 账户中的派生仓库页面点击 Pull request 将更改提交给项目维护者审核。如果维护者要求修改这很正常——核心贡献者也会遇到这种情况。请继续在本地分支工作并将修改推送到派生仓库更改会自动出现在 Pull Request 中。测试运行库测试套件仓库提供了全面的测试套件来验证库行为库测试位于 tests 目录。推荐使用pytest和pytest-xdist并行加速。在仓库根目录运行$ python -m pytest -n auto --distloadfile -s -v ./tests/实际上这就是make test的实现方式见 Makefile 中的test目标。也可以指定更小的测试范围仅验证正在开发的功能。默认情况下会跳过耗时测试设置RUN_SLOW环境变量为yes可运行这些测试——注意这将下载数十 GB 的模型文件请确保有足够的磁盘空间、良好的网络连接或充足的耐心$ RUN_SLOWyes python -m pytest -n auto --distloadfile -s -v ./tests/仓库也完全支持unittest运行方式如下$ python -m unittest discover -s tests -t . -v $ python -m unittest discover -s examples -t examples -v将派生仓库的 main 分支与上游同步为避免向上游仓库发送引用通知这会给相关 PR 添加注释并向开发者发送不必要的通知同步派生仓库 main 分支时请遵循以下步骤尽可能避免通过派生仓库的分支和 PR 来同步上游而是直接合并到派生仓库的 main 分支如果必须使用 PR请在检出分支后执行$ git checkout -b 您的同步分支名称 $ git pull --squash --no-commit upstream main $ git commit -m 提交信息不要包含 GitHub 引用 $ git push --set-upstream origin 您的分支名称风格指南对于文档字符串docstring Diffusers 遵循Google 风格指南。在编写任何公开方法的文档时应确保格式规范、兼容 markdown 渲染可参考 src/diffusers/pipelines 下现有 Pipeline 文件的 docstring 写法。总结从社区问答到新增核心组件Diffusers 为不同经验水平的贡献者提供了完整的参与阶梯。贡献的关键要点可以概括为先读设计哲学与现有代码、写可复现的 Issue、保持 PR 聚焦单一问题、用make style/make quality/make test保证代码质量、善用# Copied from机制维护一致性。无论你选择哪条路径社区都欢迎你的参与——你投入的每一分精力最终都会沉淀为整个开源生态的公共知识财富。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Diffusers 贡献指南：从提问答疑到新增 Pipeline 模型的完整参与路线
Diffusers 贡献指南从提问答疑到新增 Pipeline 模型的完整参与路线【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers本指南基于 Diffusers 官方贡献文档系统梳理了从社区问答、提交 Issue、撰写高质量 PR到构建社区 Pipeline、添加训练示例、乃至新增模型/调度器/流水线的完整贡献路径。读完本文你将掌握 Diffusers 的代码组织方式Pipeline / Model / Scheduler 三类组件、# Copied from复制机制、开发环境搭建与测试命令能够独立完成一次从 Fork 到合并的完整开源贡献。概述九种贡献方式 Diffusers 对来自开源社区的贡献持完全开放态度且所有类型的贡献都受到重视——不仅仅是代码。回答问题、帮助他人、主动交流以及改进文档对社区的价值与提交代码同等重要。下面按难度升序列出九种贡献方式49 类需要提交 PR级别贡献方式说明1在论坛或 Discord 提问/解答零门槛构建公共知识库2提交新 Issue / 发起讨论反馈 bug、功能请求、设计反馈3解答已有 Issue需要一定的库知识4修复 Good first issue入门级代码贡献Issue 通常附有解决建议5文档贡献修正拼写、修复 docstring、翻译文档6贡献社区 Pipeline在DiffusionPipeline基础上构建自定义流程7完善训练示例官方示例或研究型示例8处理 Good second issue中等难度需要较深理解9添加新 Pipeline / 模型 / 调度器最高难度需先阅读设计哲学在动手之前建议先阅读 设计哲学理解 Pipeline、模型、调度器三类组件的设计理念——如果新增组件与设计理念严重分歧将无法被合并。1. 在讨论区提问与解答构建高质量公共知识与 Diffusers 相关的任何问题都可以发布在官方论坛或 Discord 频道包括训练/推理实验报告、个人项目展示、论文解读、基于 Diffusers 的项目求助、关于扩散模型的伦理讨论等。一个关键原则是提问/回答投入的精力越多产生的公共知识质量就越高。高质量的问题或回答应具备精确性、简洁性、相关性、易于理解、可访问性和格式规范等特质。低质量的问题会拉低整个公共知识库的质量。关于渠道选择论坛内容能被搜索引擎更好地收录帖子按热度排序、便于查找历史问答也更容易被直接链接引用而 Discord 是即时聊天模式适合快速交流但信息会随时间淹没。因此建议在论坛发布优质问答若 Discord 讨论产生了有价值的结论应整理后发布到论坛以惠及更多读者。2. 提交新 Issue五类模板的使用准则GitHub Issue 仅限处理与 Diffusers 库代码含文档直接相关的技术问题无关内容应发布到论坛或 Discord。提交新 Issue 前应确认先用搜索栏确认没有重复的 Issue请勿在现有 Issue 下追加新问题应新建议题并关联相关链接使用英文提交提交前确认版本python -c import diffusers; print(diffusers.__version__)显示的版本号不低于最新版本。新 Issue 通常分为以下几类2.1 可复现的最小化错误报告不要直接粘贴整个代码文件尽量缩小问题范围规范代码格式除 Diffusers 依赖库外不包含其他外部库务必提供环境信息在终端运行diffusers-cli env将输出复制到 Issue 中。该命令由 src/diffusers/commands/env.py 中的EnvironmentCommand实现会收集 Python 版本、PyTorch 版本、diffusers 版本、CUDA 信息等关键环境数据详细说明问题及其影响确保代码片段可复现——不能因缺少库或未定义变量而无法运行应精简到可直接复制到 Python shell 运行如需特定模型/数据集请确保读者能获取可上传至 Hub并尽量保持体积最小。2.2 功能请求优质的功能请求应包含动机说明是否与库的使用痛点相关、是否因项目需求产生、是否是你已实现的功能、用完整段落描述功能特性、提供代码片段演示预期用法、论文链接如涉及、辅助材料示意图、截图等。2.3 设计反馈关于库设计的反馈正面或负面都能帮助核心维护者打造更友好的库。若某个设计选择与当前理念不符请说明原因及改进建议若某个设计对您特别实用也请留下备注——这对未来的设计决策极具参考价值。可参照 设计哲学 了解当前设计理念。2.4 技术问题主要涉及库代码的实现逻辑或特定功能模块的作用。提问时务必附上相关代码链接并详细说明难以理解的具体原因。2.5 新模型/调度器/Pipeline 提案若扩散模型社区发布了希望集成到 Diffusers 的新模型、Pipeline 或调度器请提供简要说明及论文或发布链接、开源实现链接如有、模型权重下载链接如已公开。若愿意参与开发请告知维护者以便指导并尝试通过 GitHub 账号标记原始组件作者。3. 解答已有 Issue回答 GitHub Issue 需要一定的 Diffusers 技术知识但鼓励所有人尝试参与——即使答案不完全正确。高质量回答的建议保持简洁精炼、严格聚焦问题本身、提供代码/论文等佐证材料、优先用代码说话——若代码片段能解决问题请提供完整可复现代码。面对离题、重复或无关的问题可以通过以下方式协助维护者引导提问者精确描述问题、标记重复 Issue 并附原链接、推荐用户至论坛或 Discord。4. 修复 Good first issue标有 Good first issue 标签的问题通常已说明解决方案建议。若该问题尚未关闭且想尝试解决只需留言我想尝试解决这个问题。通常有三种情况a.) 问题描述已提出解决方案——认可方案即可直接提交 PR 或草稿 PRb.) 问题描述未提出解决方案——可询问修复建议Diffusers 团队会尽快回复c.) 已有 PR 但问题未关闭——若原 PR 停滞可新开 PR 并关联原 PR若原 PR 仍活跃可通过建议、审查或协作等方式帮助原作者。5. 文档贡献优秀库必然拥有优秀文档文档是新用户的首要接触点。贡献形式包括修正拼写/语法错误、修复 docstring 格式错误如显示异常或链接失效、修正 docstring 中张量的形状/维度描述、优化晦涩或错误的说明、更新过时代码示例、文档翻译。官方文档源文件位于 docs/source 目录其中 docs/source/zh 为简体中文翻译包含本贡献指南及设计哲学等概念文档。修改文档前请查阅 docs 目录 下的验证说明。6. 贡献社区 Pipeline从零构建一个单步 Pipeline社区 Pipeline 是基于 [DiffusionPipeline] 的自定义流程任何人都能通过设置custom_pipeline参数加载使用。与 GitHub Pipeline 相比Hub Pipeline 完全可定制调度器、模型、pipeline 代码均可自定义而 GitHub Pipeline 仅限于自定义 pipeline 代码。GitHub Pipeline 需要提交 PR 经过 Diffusers 团队审查较慢Hub Pipeline 可直接上传无需审查最快。关于设立社区 Pipeline 的原因可参考 Issue #841——核心维护者无法维护 diffusion 模型所有可能的推理使用方式但也不希望限制社区构建这些流程。[!TIP] 社区 Pipeline 与官方 Pipeline 的加载方式、GitHub 与 Hub 两种托管方式的详细区别可参阅 Community pipelines and components。下面演示如何创建一个简单的单步流程——UNet 仅执行单次前向传播并调用调度器一次。该示例在仓库中真实存在examples/community/one_step_unet.py。第 1 步创建 Pipeline 类并注册组件创建one_step_unet.py文件。该文件可包含任意所需包只要用户已安装但确保仅有一个继承自DiffusionPipeline的流程类。在__init__中添加 UNet 和调度器并通过register_modules注册——这是确保流程及其组件可通过 [~DiffusionPipeline.save_pretrained] 保存的关键from diffusers import DiffusionPipeline import torch class UnetSchedulerOneForwardPipeline(DiffusionPipeline): def __init__(self, unet, scheduler): super().__init__() self.register_modules(unetunet, schedulerscheduler)register_modules是DiffusionPipeline的底层方法定义于 src/diffusers/pipelines/pipeline_utils.py 的register_modules方法它会把传入的组件注册为 pipeline 的属性并记录在model_index.json中从而支持save_pretrained/from_pretrained的完整序列化闭环。第 2 步实现__call__前向逻辑在前向传播中可添加任意功能。对于单步流程创建随机图像并通过设置timestep1调用 UNet 和调度器一次from diffusers import DiffusionPipeline import torch class UnetSchedulerOneForwardPipeline(DiffusionPipeline): def __init__(self, unet, scheduler): super().__init__() self.register_modules(unetunet, schedulerscheduler) 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注意这里直接读取了self.unet.config.in_channels和self.unet.config.sample_size——这是 Diffusers 模型配置系统的典型用法模型通过ConfigMixin暴露配置pipeline 代码据此动态构造输入张量形状无需硬编码尺寸。第 3 步运行 Pipeline现在可以通过传入 UNet 和调度器来运行流程若流程结构相同也可加载预训练权重from diffusers import DDPMScheduler, UNet2DModel scheduler DDPMScheduler() unet UNet2DModel() pipeline UnetSchedulerOneForwardPipeline(unetunet, schedulerscheduler) output pipeline() # 加载预训练权重 pipeline UnetSchedulerOneForwardPipeline.from_pretrained(google/ddpm-cifar10-32, use_safetensorsTrue) output pipeline()第 4 步选择分享方式GitHub Pipeline通过向 Diffusers 仓库提交拉取请求将one_step_unet.py添加到 examples/community 子文件夹中Hub Pipeline在 Hub 上创建模型仓库并上传one_step_unet.py文件。examples/community 目录目前收录了大量社区 Pipeline覆盖了文本到图像、图像到图像、修复、ControlNet、LoRA 加载、视频生成等丰富场景如lpw_stable_diffusion.py、pipeline_flux_with_cfg.py、pipeline_stg_wan.py等是学习社区 Pipeline 写法的绝佳素材库。7. 贡献训练示例训练示例位于 examples 目录分为两类官方训练示例examples目录下除research_projects和community外的所有文件夹由 Diffusers 核心维护者维护研究型训练示例examples/research_projects 目录由社区维护。这与官方 Pipeline 与社区 Pipeline 的区分原因相同核心维护者不可能维护 diffusion 模型所有可能的训练方法。若某种训练范式过于实验性或不够普及相应训练代码应放入research_projects并由作者维护。目录结构规范每个示例目录包含一个或多个训练脚本、requirements.txt和README.md。用户使用时需要先克隆代码库git clone https://github.com/huggingface/diffusers并安装训练所需的所有额外依赖cd diffusers pip install -e .[dev] pip install -r examples/your-example-folder/requirements.txt因此requirements.txt应定义训练示例所需的所有 pip 依赖。可参考 examples/dreambooth/requirements.txt——它声明了accelerate0.16.0、torchvision、transformers4.25.1、ftfy、tensorboard、Jinja2、peft0.7.0等依赖。脚本编写要求运行示例所需的所有代码应集中在单个 Python 文件中用户应能通过命令行python your-example.py --args直接运行示例应保持简洁目的是复现已知训练方案而非创造最先进的模型避免添加过多自定义逻辑——因此这些示例也是优质的教学材料强烈建议使用 Accelerate 库它与 Diffusers 深度集成提交前参考现有示例如 examples/dreambooth/train_dreambooth.py了解规范格式。README 要求运行示例的具体命令训练结果链接日志/模型等展示用户可预期的效果若添加非官方/研究性训练示例必须注明维护者信息含 Git 账号格式可参考 examples/research_projects/intel_opts 目录下的说明贡献官方训练示例时还需在对应目录添加测试文件如 examples/dreambooth/test_dreambooth.py非官方示例无需此步骤。8. 处理 Good second issue标有 Good second issue 标签的问题通常比 Good first issue 更复杂描述一般不会提供详细解决指引需要贡献者对库有较深理解。若想解决此类问题可直接提交 PR 并关联对应 Issue。若已有未合并的 PR请分析原因后提交改进版。注意此类 PR 的合并难度通常更高需要帮助时请大胆向核心维护者询问。9. 添加 Pipeline、模型和调度器Pipeline、模型和调度器是 Diffusers 库最重要的组成部分。添加新组件可能为依赖 Diffusers 的任何用户界面开启全新的用例。仓库中这三类组件的源码位置Pipelinesrc/diffusers/pipelines模型src/diffusers/models调度器src/diffusers/schedulers在动手之前强烈建议阅读设计哲学理解三类组件的设计理念。若新增组件与设计理念严重分歧将无法合并因为会导致 API 不一致。若从根本上不同意某个设计选择应提交设计反馈 Issue 讨论。请确保在 PR 中添加原始代码库/论文的链接并最好直接 原始作者以便他们跟踪进展并提供帮助。若在 PR 过程中遇到不确定的情况随时留言请求初步审查。# Copied from复制机制在添加任何 Pipeline、模型或调度器代码时理解# Copied from机制是独特且重要的。整个 Diffusers 代码库大量使用该机制其目的是保持代码库易于理解和维护用# Copied from标记的代码必须与复制来源的代码完全相同。这样每当运行make fix-copies时就可以轻松更新并将更改传播到多个文件。例如下面的AltDiffusionPipelineOutput使用# Copied from机制复制StableDiffusionPipelineOutput唯一的区别是将类前缀从Stable改为Alt# 从 diffusers.pipelines.stable_diffusion.pipeline_output.StableDiffusionPipelineOutput 复制并将 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. 从源码看该机制的底层实现位于 utils/check_copies.py脚本通过正则_re_copy_warning匹配# Copied from diffusers.模块.对象注释用find_code_in_diffusers定位原始对象在src/diffusers下的定义代码支持OldName-NewName替换模式并对复制代码运行ruff格式化后与现有代码比对make fix-copies则调用check_copies.py --fix_and_overwrite自动同步差异。同时Makefile 中的make style和make fixup目标也会触发repo-consistency检查包括check_dummies.py、check_repo.py、check_inits.py确保复制代码与原始代码保持一致。如何撰写优质 Issue问题描述越清晰被快速解决的可能性就越高。选择正确的模板错误报告、功能请求、API 设计反馈、新模型/Pipeline/调度器添加等在新建 Issue 时务必选择正确模板精确描述为 Issue 起恰当的标题用最简练的语言描述问题。确保一个 Issue 只针对一个问题错误报告应精确描述错误类型不应只写diffusers 出错可复现性无法复现的代码片段 无法解决问题。确保包含可复制粘贴到 Python 解释器的代码片段没有缺少导入或图片链接等问题。若涉及本地权重或数据请尝试创建虚拟模型或虚拟数据最小化原则删除所有与问题无关的代码/信息。发现错误时创建最简单的代码示例不要转储整个工作流程。训练报错时应先定位是哪部分代码导致用模拟数据替代完整数据集测试添加引用链接提及特定命名、方法或模型时务必提供引用链接不要假设读者了解你所指内容规范格式Python 代码使用代码语法块错误信息使用标准代码语法将 Issue 视为百科全书的精美词条每个规范撰写的 Issue 不仅是向维护者传递问题的途径更是帮助社区深入理解库特性的公共知识贡献。优质 PR 编写规范保持风格统一理解现有设计模式和语法规范显著偏离现有设计模式或用户界面的 PR 将不予合并聚焦单一问题每个 PR 只解决一个明确问题避免顺手修复其他问题——包含多个无关修改的 PR 会极大增加审查难度如适用添加代码片段演示新增功能的使用方法PR 标题应准确概括其核心贡献若 PR 针对某个 Issue请在描述中注明 Issue 编号以建立关联进行中的 PR 请在标题添加[WIP]前缀文本表述与格式要求参照优质 Issue 编写规范确保现有测试用例全部通过必须添加高覆盖率测试未经充分测试的代码不予合并。若新增slow测试请使用RUN_SLOW1 python -m pytest tests/test_my_new_model.py确保通过CircleCI 不执行慢速测试但 GitHub Actions 每日夜间运行所有公开方法必须包含格式规范、兼容 markdown 的 docstring避免增加仓库体积不要添加图片、视频等非文本文件。建议优先使用托管在 hf.co 的 dataset 存放这类文件外部贡献者可将图片加入 PR 并请 Hugging Face 成员迁移至该数据集。提交 PR 流程编写代码前强烈建议先搜索现有 PR 或 Issue 确认没有重复工作如有疑问建议先创建 Issue 获取反馈。贡献需要基本的git技能——在终端输入git --help即可查阅手册。按以下步骤操作1. Fork 与克隆在仓库页面点击 Fork 按钮创建代码副本至你的 GitHub 账户然后克隆 fork 并添加主仓库为远程源$ git clone gitgithub.com:您的GitHub账号/diffusers.git $ cd diffusers $ git remote add upstream https://github.com/huggingface/diffusers.git2. 创建开发分支$ git checkout -b 您的开发分支名称禁止直接在main分支上修改。3. 配置开发环境$ pip install -e .[dev]若已克隆仓库可能需要先执行git pull获取最新代码。4. 开发并确保测试通过运行受影响测试$ pip install -e .[test] $ pytest tests/待测文件.py也可运行完整测试套件需高性能机器$ make test5. 格式化与质量检查 Diffusers 使用black和isort保持代码风格统一并在此基础上使用ruff和自定义脚本检查代码错误。修改后请执行$ make style以及手动运行与 CI 相同的质量检查$ make quality从 Makefile 的源码可以看出make style会执行ruff check --fix、ruff format、doc-builder style、自动生成代码autogenerate_code和额外风格检查extra_style_checks包括custom_init_isort.py与check_doc_toc.py --fix_and_overwrite而make quality则以只读方式运行ruff check、ruff format --check、doc-builder style --check_only、check_doc_toc.py和check_ai.py验证仓库是否处于良好状态。6. 提交与推送$ git add modified_file.py $ git commit -m 关于您所做更改的描述性信息。 $ git pull upstream main # 定期同步上游变更 $ git push -u origin 此处替换为您的描述性分支名称7. 发起 Pull Request确认无误后访问你 GitHub 账户中的派生仓库页面点击 Pull request 将更改提交给项目维护者审核。如果维护者要求修改这很正常——核心贡献者也会遇到这种情况。请继续在本地分支工作并将修改推送到派生仓库更改会自动出现在 Pull Request 中。测试运行库测试套件仓库提供了全面的测试套件来验证库行为库测试位于 tests 目录。推荐使用pytest和pytest-xdist并行加速。在仓库根目录运行$ python -m pytest -n auto --distloadfile -s -v ./tests/实际上这就是make test的实现方式见 Makefile 中的test目标。也可以指定更小的测试范围仅验证正在开发的功能。默认情况下会跳过耗时测试设置RUN_SLOW环境变量为yes可运行这些测试——注意这将下载数十 GB 的模型文件请确保有足够的磁盘空间、良好的网络连接或充足的耐心$ RUN_SLOWyes python -m pytest -n auto --distloadfile -s -v ./tests/仓库也完全支持unittest运行方式如下$ python -m unittest discover -s tests -t . -v $ python -m unittest discover -s examples -t examples -v将派生仓库的 main 分支与上游同步为避免向上游仓库发送引用通知这会给相关 PR 添加注释并向开发者发送不必要的通知同步派生仓库 main 分支时请遵循以下步骤尽可能避免通过派生仓库的分支和 PR 来同步上游而是直接合并到派生仓库的 main 分支如果必须使用 PR请在检出分支后执行$ git checkout -b 您的同步分支名称 $ git pull --squash --no-commit upstream main $ git commit -m 提交信息不要包含 GitHub 引用 $ git push --set-upstream origin 您的分支名称风格指南对于文档字符串docstring Diffusers 遵循Google 风格指南。在编写任何公开方法的文档时应确保格式规范、兼容 markdown 渲染可参考 src/diffusers/pipelines 下现有 Pipeline 文件的 docstring 写法。总结从社区问答到新增核心组件Diffusers 为不同经验水平的贡献者提供了完整的参与阶梯。贡献的关键要点可以概括为先读设计哲学与现有代码、写可复现的 Issue、保持 PR 聚焦单一问题、用make style/make quality/make test保证代码质量、善用# Copied from机制维护一致性。无论你选择哪条路径社区都欢迎你的参与——你投入的每一分精力最终都会沉淀为整个开源生态的公共知识财富。【免费下载链接】diffusers Diffusers: State-of-the-art diffusion models for image, video, and audio generation in PyTorch.项目地址: https://gitcode.com/GitHub_Trending/di/diffusers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
