Diffusers 贡献指南从 Bug 报告到新 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 仓库的官方贡献文档 CONTRIBUTING.md实际指向 docs/source/en/conceptual/contribution.md整理而成覆盖从提问、提 Issue、修复 Good first issue到贡献社区 Pipeline、训练示例直至接入全新 pipeline/model/scheduler 的九级贡献路径并附 Issue/PR 写作规范、本地测试与代码质量命令make test/make style/make quality/make fix-copies、fork 同步技巧以及面向 AI Agent 协作贡献的.ai/配置体系与自审流程。读完本文你能够独立完成一次从环境搭建到 PR 提交的全流程贡献并理解仓库背后的一致性设计机制。贡献总览九种方式按难度排序Diffusers 官方将贡献方式按难度从低到高排为 9 级并明确所有贡献对社区都有价值不只有代码才值得参与级别贡献方式是否需要开 PR1在论坛 / Discord 提问与答疑否2在 GitHub Issues 开新 Issuebug / 功能请求 / 反馈 / 技术提问 / 新模型提议否3回答他人的 Issue否4修复 Good first issuegood first issue标签是5贡献文档docs/source下的 Markdown是6贡献社区 Pipelineexamples/community是7贡献训练示例examples目录是8修复 Good second issueGood second issue标签是9新增 pipeline、model 或 scheduler是49 级贡献都需要开 PR完整的开 PR 流程见本文如何打开一个 PR一节。提问与答疑选择正确的渠道官方建议所有 Diffusers 相关问题优先在论坛或 Discord 提出内容包括训练/推理实验分享、个人项目展示、论文摘要、伦理问题等。渠道选择有明确的分工论坛被搜索引擎索引得更好帖子按热度而非时间排序历史问答更容易被检索到、可以被直接引用链接——适合沉淀长期有效的高质量问答Discord聊天式快速往返回答通常更快但信息随时间沉底、难以检索。官方建议用论坛做长期知识资产Discord 讨论出有价值的结论后再把结果搬回论坛。高质量问答的标准是精确、简洁、相关、易懂、易获取、格式规范——这一标准与后文如何写好一个 Issue完全一致。边界规则GitHub Issues 只保留与 Diffusers 库代码含文档直接相关的技术问题、bug 报告、功能请求和设计反馈与库代码无关的求助应去论坛或 Discord。开好一个 Issue开 Issue 前的五条前置检查先用 GitHub Issues 搜索栏确认没有重复提问不要在其他 Issue 下蹭新话题——即使高度相关也应新开 Issue 并链接原 IssueIssue 一律用英文撰写先确认本地版本是否已是最新python -c import diffusers; print(diffusers.__version__)很多问题升级到最新版即消失Issue 写得越用心得到的回答质量越高。2.1 可复现的最小 Bug 报告官方对 bug report 的要求可归纳为把 bug 缩小到最小范围不要整段倒出代码文件只依赖 Diffusers 及其必需外部库必须提供完整环境信息——官方给定的命令是diffusers-cli env把其输出整体粘贴进 Issue。该命令由 src/diffusers/commands/env.py 实现会收集 diffusers 版本、torch / transformers / accelerate / xformers / bitsandbytes / peft / safetensors 等依赖的可用性与版本、平台信息解释清楚问题是什么、为什么是问题代码片段必须能原样粘贴进 Python shell 运行不能缺 import、不能引用未定义的变量若复现需要模型或数据集应上传到 Hub或构造 dummy 模型/数据保证他人可访问并尽量小。2.2 功能请求Feature Request一份高质量功能请求要覆盖五点先讲动机是库的某个缺陷/痛点最好附演示代码是项目需要还是自己实现过、觉得值得回馈社区用完整的一段话描述该功能给出展示未来用法的代码片段若涉及论文附论文链接附上其他可能有用的材料图示、截图等。2.3 设计反馈对 API 设计的反馈对核心维护者极有价值。官方要求反馈前先理解现有设计哲学docs/source/en/conceptual/philosophy.md仓库根目录的 PHILOSOPHY.md 是它的符号链接某设计选择与哲学不符、或哲学执行过度限制了用例都说明为什么 应如何改某设计对你非常有用也值得留言作为后续设计决策的输入。2.4 技术提问即这段代码为什么这样写 / 某个部分做什么。要求链接到被问的代码并说明具体哪里难以理解。2.5 提议接入新的 model / scheduler / pipeline需要提供组件的简短描述与论文或公开发布链接、开源实现链接如有、模型权重链接如有。若你本人愿意接手实现请在 Issue 中说明以便维护者给出指引并尽量按 GitHub handle 原作者。如何写好一个 Issue七条准则官方原文强调写得越好被快速解决的概率越高选对模板Bug Report、Feature Request、API 设计反馈、新 model/pipeline/scheduler 接入、Forum 或空白模板精确标题贴切一个 Issue 只讲一个问题发现多个就开多个bug 要写清楚具体错在哪而不是一句 Error in diffusers可复现没有可复现代码片段 没有解决方案。Issue 必须同时包含错误信息和可原样粘贴复现同一错误的代码片段引用本地无法访问的权重/数据会导致 Issue 无法解决此时应构造 dummy 模型或 dummy 数据最小化删除一切无关代码与信息。训练中途报错时先定位是训练代码的哪一部分负责该错误用几行代码复现用 dummy 数据替代完整数据集加链接提到的命名、方法、模型、PR、Issue 都要给链接不要假设读者知道你在说什么格式化代码用 Python 语法块、报错用普通代码块把 Issue 当作百科词条每个写得好的 Issue 都是对公共知识的贡献能帮助整个社区理解库的某个侧面。贡献社区 Pipeline一个可运行的 one-step 示例社区 Pipeline 建立在 [DiffusionPipeline] 基类之上用户通过custom_pipeline参数加载使用。它存在的原因是核心维护者无法维护扩散模型推理的所有可能方式但又不希望阻止社区自建方案。官方文档用一个最简例子贯穿UNet 只跑一次前向、scheduler 只调用一次one-step。第 1 步新建one_step_unet.py文件内可以使用任何用户已安装的包只保留一个继承DiffusionPipeline的类__init__中通过register_modules注册组件这是让 Pipeline 与组件能随 [~DiffusionPipeline.save_pretrained] 保存的前提from diffusers import DiffusionPipeline import torch class UnetSchedulerOneForwardPipeline(DiffusionPipeline): def __init__(self, unet, scheduler): super().__init__() self.register_modules(unetunet, schedulerscheduler)第 2 步前向逻辑建议定义为__call__。one-step 版本创建一张随机图以timestep1各调用一次 UNet 与 schedulerfrom 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第 3 步传入组件直接运行或在 Pipeline 结构一致时加载预训练权重from diffusers import DDPMScheduler, UNet2DModel scheduler DDPMScheduler() unet UNet2DModel() pipeline UnetSchedulerOneForwardPipeline(unetunet, schedulerscheduler) output pipeline() # load pretrained weights pipeline UnetSchedulerOneForwardPipeline.from_pretrained(google/ddpm-cifar10-32, use_safetensorsTrue) output pipeline()分发方式二选一GitHub 社区 Pipeline向 Diffusers 仓库提 PR把one_step_unet.py加入 examples/community 子目录——该目录下 one_step_unet.py 就是官方给出的同款示例Hub 社区 Pipeline在 Hub 建一个模型仓库并上传该文件用户即可通过custom_pipeline远程加载。更完整的机制说明见 docs/source/en/using-diffusers/custom_pipeline_overview.md。贡献训练示例两种类型与文件结构Diffusers 训练示例集中在 examples 目录分两类官方训练示例examples下除research_projects和community之外的所有文件夹由核心维护者维护研究性训练示例位于 examples/research_projects由作者本人维护。划分逻辑与官方 vs 社区 Pipeline一致核心维护者不可能维护所有扩散模型训练方法过于实验性或不够流行的训练范式应放进research_projects。两类示例的目录结构相同一个或多个训练脚本 requirements.txtREADME.md。用户侧的使用方式是git clone https://github.com/huggingface/diffusers cd diffusers pip install -r examples/your-example-folder/requirements.txt因此requirements.txt必须完整声明运行该示例所需的全部 pip 依赖可参考 examples/dreambooth/requirements.txt。官方对训练示例的哲学要求运行所需的全部代码集中在单个 Python 文件里能用python your-example.py --args从命令行直接跑起来保持简单目的是演示如何用 Diffusers 训练而非刷出 SOTA 模型顺带使其成为好的教学材料。新增示例时强烈建议先读 examples/dreambooth/train_dreambooth.py 这类现有示例官方强烈建议使用与 Diffusers 深度集成的 Accelerate 库。示例跑通后README.md必须包含示例运行命令、训练结果日志/模型链接若是研究性示例还需注明本人维护本示例并带上 git handle。贡献官方示例还必须在该文件夹内加测试如 examples/dreambooth/test_dreambooth.py研究性示例不强制。接入新 pipeline / model / scheduler先读设计哲学理解# Copied from接入新的 pipeline、model 或 scheduler 是最高级别的贡献。官方要求先读设计哲学PHILOSOPHY.md / docs/source/en/conceptual/philosophy.md。与现有设计哲学严重偏离的接入不会被合并因为会导致 API 不一致若你认为某个设计决策本身应该变应提 Feedback Issue 而不是在 PR 里自创一套PR 中附上原始代码库/论文链接并尽量在 PR 上直接 原作者卡住时直接留言请求初审。# Copied from机制全仓库一致性的底层保障新增任何 pipeline/model/scheduler 代码前必须理解# Copied from机制——它遍布整个 Diffusers 代码库作用是强制被标记代码与其来源保持逐字一致从而使一处修改能通过make fix-copies自动传播到所有派生文件。官方给出的例子StableDiffusionPipelineOutput是源头AltDiffusionPipelineOutput通过该机制复制它唯一差异是类名前缀从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. 从源码结构看该机制的源头定义在 src/diffusers/pipelines/stable_diffusion/pipeline_output.py而 AltDiffusion 管线已归入 src/diffusers/pipelines/deprecated/alt_diffusion/正是其派生者# Copied from注释在src/diffusers下有大量实例如 src/diffusers/schedulers/scheduling_pndm.py 等 scheduler 文件。对应的自动化实现是 utils/check_copies.py由 Makefile 的fix-copies目标驱动fix-copies: python utils/check_copies.py --fix_and_overwrite python utils/check_dummies.py --fix_and_overwrite实践含义你不应手工维护复制改前缀的代码块——写一处、标记一处让make fix-copies统一同步。如何写好一个 PR十一条规则做变色龙理解现有设计模式与语法让新代码无缝融入显著偏离现有模式或用户界面的 PR 不会合并激光聚焦一个 PR 只解决一个问题警惕顺手再修一个的陷阱有帮助时附上展示新用法示例的代码片段PR 标题是贡献内容的摘要PR 解决某 Issue 时在描述中写 Issue 编号以建立关联进行中的 PR 用[WIP]前缀避免重复劳动文案按如何写好一个 Issue的标准来写确保现有测试通过没有高质量测试 不合并。新增slow测试要能用RUN_SLOW1 python -m pytest tests/test_my_new_model.py跑通CI 中慢测试由夜间任务执行所有公共方法必须有对 Markdown 友好的 docstring官方指认 src/diffusers/pipelines/latent_diffusion/pipeline_latent_diffusion.py 为范例不要向仓库加入会显著增重仓库的文件图片、视频等非文本文件应放在 Hub 托管的数据集如hf-internal-testing中外部贡献可先放进 PR再请 Hugging Face 成员迁移。如何打开一个 PR从 fork 到提交前置动作先搜索现有 PR 与 Issue 确认没人做同一件事不确定就先开 Issue 征求反馈。完整步骤Fork 仓库克隆你的 fork 并添加上游 remote$ git clone gitgithub.com:your GitHub handle/diffusers.git $ cd diffusers $ git remote add upstream https://github.com/huggingface/diffusers.git建开发分支不要直接在main上工作$ git checkout -b a-descriptive-name-for-my-changes在虚拟环境中安装开发依赖$ pip install -e .[dev]从 setup.py 可见dev额外依赖是quality test training docs torch的组合extras[dev] extras[quality] extras[test] extras[training] extras[docs] extras[torch]而 pyproject.toml 声明python_requires3.10.0。已克隆过仓库的话可能需要先git pull拉取最新变更。在分支上开发并保证测试通过。安装测试依赖后按受影响范围运行$ pip install -e .[test] $ pytest tests/TEST_TO_RUN.py跑全量测试$ make test注意文档此处说 Diffusers 使用black和isort做格式化但从当前 pyproject.toml 与 Makefile 看仓库实际已切换到ruffruff checkruff format行宽 119双引号、空格缩进isort 规则并入tool.ruff.lint.isort文档表述与当前工具链存在代际差异以仓库配置为准。风格修正与不可自动化的检查$ make style $ make qualitymake quality在 Makefile 中对应ruff check、ruff format --check、doc-builder style行宽 119以及utils/check_doc_toc.py、utils/check_ai.py等自定义检查make style则是带--fix的自动修正版本并串联autogenerate_code更新src/diffusers/dependency_versions_table.py与extra_style_checksutils/custom_init_isort.py、utils/check_doc_toc.py --fix_and_overwrite。提交并推送$ 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在 fork 页面点 Pull request 提交给维护者评审维护者要求修改时在本地分支继续改并 push改动会自动出现在 PR 中——这对核心贡献者也一样平常。测试体系pytest 与 RUN_SLOW测试套件位于 tests 目录models、pipelines、schedulers、hooks、lora、quantization 等子目录示例测试位于 examples/conftest.py 之下。官方推荐pytestpytest-xdist更快仓库根目录下$ python -m pytest -n auto --distloadfile -s -v ./tests/这正是make test的实现方式见 Makefile 中test:目标。慢测试默认跳过设置RUN_SLOWyes才会运行——它会下载数 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同步 fork 的 main 与上游 main为避免在同步时触发对上游 PR 的 ping 与不必要的通知官方要求尽可能避免在 fork 里建分支 走 PR的方式同步上游而是直接合入 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提交信息中不要包含 GitHub 引用避免#xxx触发跨仓库 ping。风格指南文档字符串docstring遵循 Google 风格指南公共方法的 docstring 需与 Markdown 渲染兼容。用 AI Agent 协作贡献.ai/配置、Skills 与自审流程文档对 AI Agent 贡献单列了规范仓库内配置真实存在且结构清晰配置位置Agent 配置集中在 .ai/ 目录同时以 agent plugin 形式发布可按需安装任务级 skill。根目录的 AGENTS.md 与 CLAUDE.md 都是指向.ai/AGENTS.md的符号链接保证每个 agent 会话都加载同一份顶层规范对贡献者只读.ai/由核心维护者维护PR 中不要修改.ai/下任何文件含根级符号链接与安装后的.agents/skills/.claude/skills发现问题应开 Issue 或在 PR 中标记由维护者更新参考指南.ai/references/下按需加载当前仓库中实际包含 models.md、pipelines.md、modular.md、testing.md、review-rules.md 等models.md— 注意力模式、模型实现规则、通用约定pipelines.md— pipeline 约定modular.md— modular pipeline 约定与转换检查清单testing.md— 必备测试层级、tester mixin、dummy 组件规则review-rules.md— 评审者关注点Skills.ai/skills/ 下按任务按需加载当前仓库中实际存在 4 个model-integration— 端到端向 diffusers 接入新模型/管线文件结构、集成检查清单、测试布局、权重转换self-review— 开 PR 前按项目规则审查自己的改动diffusers-cli— 在终端运行 pipeline、检查 schemacustom-blocks— 为 Hub 打包ModularPipelineBlocks子类。skill 的安装由 CLI 支撑src/diffusers/commands/skills.py 实现了diffusers-cli skills命令会把.ai/skills/name/下的 skill bundle 安装到各 agent 的发现路径Claude Code 读.claude/skills/Codex/Cursor 读.agents/skills/name/并按 skill 引用的references/guide.md自动携带所需指南副本。开始编码前让 agent 确认自身环境$ python utils/check_ai.py # 校验 .ai/ 指南与 skills 的一致性 $ diffusers-cli skills list # 查看当前 agent 实际装了哪些 skillutils/check_ai.py 检查三件会随文件移动而断裂的事相对链接不逃出 skill 自身目录、skill 引用的references/guide.md确实存在于.ai/references/、其余相对链接可解析且 skill frontmatter 的name与目录名一致。该检查也被纳入make quality作为 CI 质量门禁的一部分。AI 辅助贡献的硬性要求AI 辅助贡献被欢迎但必须有协调、有范围、有验证否则 PR 可能不被详细评审直接关闭开 PR 前先协调找到或开出 Issue查过相似 PR开放与近期关闭的等维护者在 Issue 上明确表态认可后再开 PR修模式不修个例发现反复出现的问题全库搜索同类实例开单个范围清晰的系统性 Issue如修复所有 scheduler 中的可变默认参数而不是每个实例各开一个开 PR 前自审运行self-reviewskill——它按 review-rules.md与 CI 评审者同一把尺子审查你的 diff。它是助手而非权威可能出错处理你认为合理的阻断性问题尽可能清理死代码不同意的建议可以留给评审者通过下面的备注说明这是有意为之分享自审报告把最终一轮对应你提交的 diff 的自审报告贴进 PR 描述或评论包括故意不修的发现及原因PR 描述必须包含协调链接维护者认可工作的 Issue/讨论、实际运行的测试命令及输出粘贴结果而非一句测试通过、自审报告或其链接。模型作者或官方维护团队被鼓励用 agent 完成新模型接入遵循 AGENTS.md 的推荐配置并使用model-integrationskill开 PR 前与维护者协调范围。文档贡献与代码质量速查文档贡献的合法范围包括错别字与语法、docstring 排版、docstring 张量形状/维度、难懂或有误的说明、过时代码示例、翻译。任何出现在官方文档页面上的内容其源头都在 docs/source 下可修改。把本文的命令汇总成一份贡献者速查表目的命令安装开发环境pip install -e .[dev]安装测试依赖pip install -e .[test]跑单个测试pytest tests/TEST_TO_RUN.py跑全量测试make test跑慢测试RUN_SLOWyes python -m pytest -n auto --distloadfile -s -v ./tests/自动风格修正make style质量检查只查不改make quality同步# Copied from代码块make fix-copies只修改动文件的快速通道make fixup环境信息贴进 bug 报告diffusers-cli env校验.ai/配置一致性python utils/check_ai.py查看已安装 agent skillsdiffusers-cli skills list其中make fixupMakefile 中定义为modified_only_fixup extra_style_checks autogenerate_code repo-consistency只对自分支创建以来被修改的文件执行ruff check --fix与ruff format是增量开发时的快速修正入口repo-consistency则串联utils/check_dummies.py、utils/check_repo.py、utils/check_inits.py、utils/check_forward_call_docstrings.py四个仓库一致性检查。关键文件索引docs/source/en/conceptual/contribution.md本文依据的官方贡献文档根目录 CONTRIBUTING.md 是其符号链接docs/source/en/conceptual/philosophy.md接入新组件前必读的设计哲学Makefiletest/style/quality/fix-copies/fixup全部质量命令的实现pyproject.tomlruff lint/format/isort 配置行宽 119、双引号setup.pydev/test等 extras 依赖组合python_requires3.10examples/community/one_step_unet.py社区 Pipeline 官方示例examples/dreambooth/train_dreambooth.py、examples/dreambooth/test_dreambooth.py训练示例脚本与其配套测试的样板utils/check_copies.py、utils/check_ai.py# Copied from同步与.ai/一致性检查src/diffusers/commands/env.py、src/diffusers/commands/skills.pydiffusers-cli env与diffusers-cli skills的实现.ai/、AGENTS.mdAI Agent 贡献的规范与 skills 入口【免费下载链接】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 贡献指南：从 Bug 报告到新 Pipeline 接入的完整工作流
Diffusers 贡献指南从 Bug 报告到新 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 仓库的官方贡献文档 CONTRIBUTING.md实际指向 docs/source/en/conceptual/contribution.md整理而成覆盖从提问、提 Issue、修复 Good first issue到贡献社区 Pipeline、训练示例直至接入全新 pipeline/model/scheduler 的九级贡献路径并附 Issue/PR 写作规范、本地测试与代码质量命令make test/make style/make quality/make fix-copies、fork 同步技巧以及面向 AI Agent 协作贡献的.ai/配置体系与自审流程。读完本文你能够独立完成一次从环境搭建到 PR 提交的全流程贡献并理解仓库背后的一致性设计机制。贡献总览九种方式按难度排序Diffusers 官方将贡献方式按难度从低到高排为 9 级并明确所有贡献对社区都有价值不只有代码才值得参与级别贡献方式是否需要开 PR1在论坛 / Discord 提问与答疑否2在 GitHub Issues 开新 Issuebug / 功能请求 / 反馈 / 技术提问 / 新模型提议否3回答他人的 Issue否4修复 Good first issuegood first issue标签是5贡献文档docs/source下的 Markdown是6贡献社区 Pipelineexamples/community是7贡献训练示例examples目录是8修复 Good second issueGood second issue标签是9新增 pipeline、model 或 scheduler是49 级贡献都需要开 PR完整的开 PR 流程见本文如何打开一个 PR一节。提问与答疑选择正确的渠道官方建议所有 Diffusers 相关问题优先在论坛或 Discord 提出内容包括训练/推理实验分享、个人项目展示、论文摘要、伦理问题等。渠道选择有明确的分工论坛被搜索引擎索引得更好帖子按热度而非时间排序历史问答更容易被检索到、可以被直接引用链接——适合沉淀长期有效的高质量问答Discord聊天式快速往返回答通常更快但信息随时间沉底、难以检索。官方建议用论坛做长期知识资产Discord 讨论出有价值的结论后再把结果搬回论坛。高质量问答的标准是精确、简洁、相关、易懂、易获取、格式规范——这一标准与后文如何写好一个 Issue完全一致。边界规则GitHub Issues 只保留与 Diffusers 库代码含文档直接相关的技术问题、bug 报告、功能请求和设计反馈与库代码无关的求助应去论坛或 Discord。开好一个 Issue开 Issue 前的五条前置检查先用 GitHub Issues 搜索栏确认没有重复提问不要在其他 Issue 下蹭新话题——即使高度相关也应新开 Issue 并链接原 IssueIssue 一律用英文撰写先确认本地版本是否已是最新python -c import diffusers; print(diffusers.__version__)很多问题升级到最新版即消失Issue 写得越用心得到的回答质量越高。2.1 可复现的最小 Bug 报告官方对 bug report 的要求可归纳为把 bug 缩小到最小范围不要整段倒出代码文件只依赖 Diffusers 及其必需外部库必须提供完整环境信息——官方给定的命令是diffusers-cli env把其输出整体粘贴进 Issue。该命令由 src/diffusers/commands/env.py 实现会收集 diffusers 版本、torch / transformers / accelerate / xformers / bitsandbytes / peft / safetensors 等依赖的可用性与版本、平台信息解释清楚问题是什么、为什么是问题代码片段必须能原样粘贴进 Python shell 运行不能缺 import、不能引用未定义的变量若复现需要模型或数据集应上传到 Hub或构造 dummy 模型/数据保证他人可访问并尽量小。2.2 功能请求Feature Request一份高质量功能请求要覆盖五点先讲动机是库的某个缺陷/痛点最好附演示代码是项目需要还是自己实现过、觉得值得回馈社区用完整的一段话描述该功能给出展示未来用法的代码片段若涉及论文附论文链接附上其他可能有用的材料图示、截图等。2.3 设计反馈对 API 设计的反馈对核心维护者极有价值。官方要求反馈前先理解现有设计哲学docs/source/en/conceptual/philosophy.md仓库根目录的 PHILOSOPHY.md 是它的符号链接某设计选择与哲学不符、或哲学执行过度限制了用例都说明为什么 应如何改某设计对你非常有用也值得留言作为后续设计决策的输入。2.4 技术提问即这段代码为什么这样写 / 某个部分做什么。要求链接到被问的代码并说明具体哪里难以理解。2.5 提议接入新的 model / scheduler / pipeline需要提供组件的简短描述与论文或公开发布链接、开源实现链接如有、模型权重链接如有。若你本人愿意接手实现请在 Issue 中说明以便维护者给出指引并尽量按 GitHub handle 原作者。如何写好一个 Issue七条准则官方原文强调写得越好被快速解决的概率越高选对模板Bug Report、Feature Request、API 设计反馈、新 model/pipeline/scheduler 接入、Forum 或空白模板精确标题贴切一个 Issue 只讲一个问题发现多个就开多个bug 要写清楚具体错在哪而不是一句 Error in diffusers可复现没有可复现代码片段 没有解决方案。Issue 必须同时包含错误信息和可原样粘贴复现同一错误的代码片段引用本地无法访问的权重/数据会导致 Issue 无法解决此时应构造 dummy 模型或 dummy 数据最小化删除一切无关代码与信息。训练中途报错时先定位是训练代码的哪一部分负责该错误用几行代码复现用 dummy 数据替代完整数据集加链接提到的命名、方法、模型、PR、Issue 都要给链接不要假设读者知道你在说什么格式化代码用 Python 语法块、报错用普通代码块把 Issue 当作百科词条每个写得好的 Issue 都是对公共知识的贡献能帮助整个社区理解库的某个侧面。贡献社区 Pipeline一个可运行的 one-step 示例社区 Pipeline 建立在 [DiffusionPipeline] 基类之上用户通过custom_pipeline参数加载使用。它存在的原因是核心维护者无法维护扩散模型推理的所有可能方式但又不希望阻止社区自建方案。官方文档用一个最简例子贯穿UNet 只跑一次前向、scheduler 只调用一次one-step。第 1 步新建one_step_unet.py文件内可以使用任何用户已安装的包只保留一个继承DiffusionPipeline的类__init__中通过register_modules注册组件这是让 Pipeline 与组件能随 [~DiffusionPipeline.save_pretrained] 保存的前提from diffusers import DiffusionPipeline import torch class UnetSchedulerOneForwardPipeline(DiffusionPipeline): def __init__(self, unet, scheduler): super().__init__() self.register_modules(unetunet, schedulerscheduler)第 2 步前向逻辑建议定义为__call__。one-step 版本创建一张随机图以timestep1各调用一次 UNet 与 schedulerfrom 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第 3 步传入组件直接运行或在 Pipeline 结构一致时加载预训练权重from diffusers import DDPMScheduler, UNet2DModel scheduler DDPMScheduler() unet UNet2DModel() pipeline UnetSchedulerOneForwardPipeline(unetunet, schedulerscheduler) output pipeline() # load pretrained weights pipeline UnetSchedulerOneForwardPipeline.from_pretrained(google/ddpm-cifar10-32, use_safetensorsTrue) output pipeline()分发方式二选一GitHub 社区 Pipeline向 Diffusers 仓库提 PR把one_step_unet.py加入 examples/community 子目录——该目录下 one_step_unet.py 就是官方给出的同款示例Hub 社区 Pipeline在 Hub 建一个模型仓库并上传该文件用户即可通过custom_pipeline远程加载。更完整的机制说明见 docs/source/en/using-diffusers/custom_pipeline_overview.md。贡献训练示例两种类型与文件结构Diffusers 训练示例集中在 examples 目录分两类官方训练示例examples下除research_projects和community之外的所有文件夹由核心维护者维护研究性训练示例位于 examples/research_projects由作者本人维护。划分逻辑与官方 vs 社区 Pipeline一致核心维护者不可能维护所有扩散模型训练方法过于实验性或不够流行的训练范式应放进research_projects。两类示例的目录结构相同一个或多个训练脚本 requirements.txtREADME.md。用户侧的使用方式是git clone https://github.com/huggingface/diffusers cd diffusers pip install -r examples/your-example-folder/requirements.txt因此requirements.txt必须完整声明运行该示例所需的全部 pip 依赖可参考 examples/dreambooth/requirements.txt。官方对训练示例的哲学要求运行所需的全部代码集中在单个 Python 文件里能用python your-example.py --args从命令行直接跑起来保持简单目的是演示如何用 Diffusers 训练而非刷出 SOTA 模型顺带使其成为好的教学材料。新增示例时强烈建议先读 examples/dreambooth/train_dreambooth.py 这类现有示例官方强烈建议使用与 Diffusers 深度集成的 Accelerate 库。示例跑通后README.md必须包含示例运行命令、训练结果日志/模型链接若是研究性示例还需注明本人维护本示例并带上 git handle。贡献官方示例还必须在该文件夹内加测试如 examples/dreambooth/test_dreambooth.py研究性示例不强制。接入新 pipeline / model / scheduler先读设计哲学理解# Copied from接入新的 pipeline、model 或 scheduler 是最高级别的贡献。官方要求先读设计哲学PHILOSOPHY.md / docs/source/en/conceptual/philosophy.md。与现有设计哲学严重偏离的接入不会被合并因为会导致 API 不一致若你认为某个设计决策本身应该变应提 Feedback Issue 而不是在 PR 里自创一套PR 中附上原始代码库/论文链接并尽量在 PR 上直接 原作者卡住时直接留言请求初审。# Copied from机制全仓库一致性的底层保障新增任何 pipeline/model/scheduler 代码前必须理解# Copied from机制——它遍布整个 Diffusers 代码库作用是强制被标记代码与其来源保持逐字一致从而使一处修改能通过make fix-copies自动传播到所有派生文件。官方给出的例子StableDiffusionPipelineOutput是源头AltDiffusionPipelineOutput通过该机制复制它唯一差异是类名前缀从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. 从源码结构看该机制的源头定义在 src/diffusers/pipelines/stable_diffusion/pipeline_output.py而 AltDiffusion 管线已归入 src/diffusers/pipelines/deprecated/alt_diffusion/正是其派生者# Copied from注释在src/diffusers下有大量实例如 src/diffusers/schedulers/scheduling_pndm.py 等 scheduler 文件。对应的自动化实现是 utils/check_copies.py由 Makefile 的fix-copies目标驱动fix-copies: python utils/check_copies.py --fix_and_overwrite python utils/check_dummies.py --fix_and_overwrite实践含义你不应手工维护复制改前缀的代码块——写一处、标记一处让make fix-copies统一同步。如何写好一个 PR十一条规则做变色龙理解现有设计模式与语法让新代码无缝融入显著偏离现有模式或用户界面的 PR 不会合并激光聚焦一个 PR 只解决一个问题警惕顺手再修一个的陷阱有帮助时附上展示新用法示例的代码片段PR 标题是贡献内容的摘要PR 解决某 Issue 时在描述中写 Issue 编号以建立关联进行中的 PR 用[WIP]前缀避免重复劳动文案按如何写好一个 Issue的标准来写确保现有测试通过没有高质量测试 不合并。新增slow测试要能用RUN_SLOW1 python -m pytest tests/test_my_new_model.py跑通CI 中慢测试由夜间任务执行所有公共方法必须有对 Markdown 友好的 docstring官方指认 src/diffusers/pipelines/latent_diffusion/pipeline_latent_diffusion.py 为范例不要向仓库加入会显著增重仓库的文件图片、视频等非文本文件应放在 Hub 托管的数据集如hf-internal-testing中外部贡献可先放进 PR再请 Hugging Face 成员迁移。如何打开一个 PR从 fork 到提交前置动作先搜索现有 PR 与 Issue 确认没人做同一件事不确定就先开 Issue 征求反馈。完整步骤Fork 仓库克隆你的 fork 并添加上游 remote$ git clone gitgithub.com:your GitHub handle/diffusers.git $ cd diffusers $ git remote add upstream https://github.com/huggingface/diffusers.git建开发分支不要直接在main上工作$ git checkout -b a-descriptive-name-for-my-changes在虚拟环境中安装开发依赖$ pip install -e .[dev]从 setup.py 可见dev额外依赖是quality test training docs torch的组合extras[dev] extras[quality] extras[test] extras[training] extras[docs] extras[torch]而 pyproject.toml 声明python_requires3.10.0。已克隆过仓库的话可能需要先git pull拉取最新变更。在分支上开发并保证测试通过。安装测试依赖后按受影响范围运行$ pip install -e .[test] $ pytest tests/TEST_TO_RUN.py跑全量测试$ make test注意文档此处说 Diffusers 使用black和isort做格式化但从当前 pyproject.toml 与 Makefile 看仓库实际已切换到ruffruff checkruff format行宽 119双引号、空格缩进isort 规则并入tool.ruff.lint.isort文档表述与当前工具链存在代际差异以仓库配置为准。风格修正与不可自动化的检查$ make style $ make qualitymake quality在 Makefile 中对应ruff check、ruff format --check、doc-builder style行宽 119以及utils/check_doc_toc.py、utils/check_ai.py等自定义检查make style则是带--fix的自动修正版本并串联autogenerate_code更新src/diffusers/dependency_versions_table.py与extra_style_checksutils/custom_init_isort.py、utils/check_doc_toc.py --fix_and_overwrite。提交并推送$ 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在 fork 页面点 Pull request 提交给维护者评审维护者要求修改时在本地分支继续改并 push改动会自动出现在 PR 中——这对核心贡献者也一样平常。测试体系pytest 与 RUN_SLOW测试套件位于 tests 目录models、pipelines、schedulers、hooks、lora、quantization 等子目录示例测试位于 examples/conftest.py 之下。官方推荐pytestpytest-xdist更快仓库根目录下$ python -m pytest -n auto --distloadfile -s -v ./tests/这正是make test的实现方式见 Makefile 中test:目标。慢测试默认跳过设置RUN_SLOWyes才会运行——它会下载数 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同步 fork 的 main 与上游 main为避免在同步时触发对上游 PR 的 ping 与不必要的通知官方要求尽可能避免在 fork 里建分支 走 PR的方式同步上游而是直接合入 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提交信息中不要包含 GitHub 引用避免#xxx触发跨仓库 ping。风格指南文档字符串docstring遵循 Google 风格指南公共方法的 docstring 需与 Markdown 渲染兼容。用 AI Agent 协作贡献.ai/配置、Skills 与自审流程文档对 AI Agent 贡献单列了规范仓库内配置真实存在且结构清晰配置位置Agent 配置集中在 .ai/ 目录同时以 agent plugin 形式发布可按需安装任务级 skill。根目录的 AGENTS.md 与 CLAUDE.md 都是指向.ai/AGENTS.md的符号链接保证每个 agent 会话都加载同一份顶层规范对贡献者只读.ai/由核心维护者维护PR 中不要修改.ai/下任何文件含根级符号链接与安装后的.agents/skills/.claude/skills发现问题应开 Issue 或在 PR 中标记由维护者更新参考指南.ai/references/下按需加载当前仓库中实际包含 models.md、pipelines.md、modular.md、testing.md、review-rules.md 等models.md— 注意力模式、模型实现规则、通用约定pipelines.md— pipeline 约定modular.md— modular pipeline 约定与转换检查清单testing.md— 必备测试层级、tester mixin、dummy 组件规则review-rules.md— 评审者关注点Skills.ai/skills/ 下按任务按需加载当前仓库中实际存在 4 个model-integration— 端到端向 diffusers 接入新模型/管线文件结构、集成检查清单、测试布局、权重转换self-review— 开 PR 前按项目规则审查自己的改动diffusers-cli— 在终端运行 pipeline、检查 schemacustom-blocks— 为 Hub 打包ModularPipelineBlocks子类。skill 的安装由 CLI 支撑src/diffusers/commands/skills.py 实现了diffusers-cli skills命令会把.ai/skills/name/下的 skill bundle 安装到各 agent 的发现路径Claude Code 读.claude/skills/Codex/Cursor 读.agents/skills/name/并按 skill 引用的references/guide.md自动携带所需指南副本。开始编码前让 agent 确认自身环境$ python utils/check_ai.py # 校验 .ai/ 指南与 skills 的一致性 $ diffusers-cli skills list # 查看当前 agent 实际装了哪些 skillutils/check_ai.py 检查三件会随文件移动而断裂的事相对链接不逃出 skill 自身目录、skill 引用的references/guide.md确实存在于.ai/references/、其余相对链接可解析且 skill frontmatter 的name与目录名一致。该检查也被纳入make quality作为 CI 质量门禁的一部分。AI 辅助贡献的硬性要求AI 辅助贡献被欢迎但必须有协调、有范围、有验证否则 PR 可能不被详细评审直接关闭开 PR 前先协调找到或开出 Issue查过相似 PR开放与近期关闭的等维护者在 Issue 上明确表态认可后再开 PR修模式不修个例发现反复出现的问题全库搜索同类实例开单个范围清晰的系统性 Issue如修复所有 scheduler 中的可变默认参数而不是每个实例各开一个开 PR 前自审运行self-reviewskill——它按 review-rules.md与 CI 评审者同一把尺子审查你的 diff。它是助手而非权威可能出错处理你认为合理的阻断性问题尽可能清理死代码不同意的建议可以留给评审者通过下面的备注说明这是有意为之分享自审报告把最终一轮对应你提交的 diff 的自审报告贴进 PR 描述或评论包括故意不修的发现及原因PR 描述必须包含协调链接维护者认可工作的 Issue/讨论、实际运行的测试命令及输出粘贴结果而非一句测试通过、自审报告或其链接。模型作者或官方维护团队被鼓励用 agent 完成新模型接入遵循 AGENTS.md 的推荐配置并使用model-integrationskill开 PR 前与维护者协调范围。文档贡献与代码质量速查文档贡献的合法范围包括错别字与语法、docstring 排版、docstring 张量形状/维度、难懂或有误的说明、过时代码示例、翻译。任何出现在官方文档页面上的内容其源头都在 docs/source 下可修改。把本文的命令汇总成一份贡献者速查表目的命令安装开发环境pip install -e .[dev]安装测试依赖pip install -e .[test]跑单个测试pytest tests/TEST_TO_RUN.py跑全量测试make test跑慢测试RUN_SLOWyes python -m pytest -n auto --distloadfile -s -v ./tests/自动风格修正make style质量检查只查不改make quality同步# Copied from代码块make fix-copies只修改动文件的快速通道make fixup环境信息贴进 bug 报告diffusers-cli env校验.ai/配置一致性python utils/check_ai.py查看已安装 agent skillsdiffusers-cli skills list其中make fixupMakefile 中定义为modified_only_fixup extra_style_checks autogenerate_code repo-consistency只对自分支创建以来被修改的文件执行ruff check --fix与ruff format是增量开发时的快速修正入口repo-consistency则串联utils/check_dummies.py、utils/check_repo.py、utils/check_inits.py、utils/check_forward_call_docstrings.py四个仓库一致性检查。关键文件索引docs/source/en/conceptual/contribution.md本文依据的官方贡献文档根目录 CONTRIBUTING.md 是其符号链接docs/source/en/conceptual/philosophy.md接入新组件前必读的设计哲学Makefiletest/style/quality/fix-copies/fixup全部质量命令的实现pyproject.tomlruff lint/format/isort 配置行宽 119、双引号setup.pydev/test等 extras 依赖组合python_requires3.10examples/community/one_step_unet.py社区 Pipeline 官方示例examples/dreambooth/train_dreambooth.py、examples/dreambooth/test_dreambooth.py训练示例脚本与其配套测试的样板utils/check_copies.py、utils/check_ai.py# Copied from同步与.ai/一致性检查src/diffusers/commands/env.py、src/diffusers/commands/skills.pydiffusers-cli env与diffusers-cli skills的实现.ai/、AGENTS.mdAI Agent 贡献的规范与 skills 入口【免费下载链接】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），仅供参考