当前位置：首页 > ops >正文

PyTorch 社区贡献和设计原则

ops 2025/8/21 9:28:08

文章目录

PyTorch 治理体系 | 构建与持续集成
- 一、如何新增维护者
PyTorch 贡献指南
- 一、贡献流程
- 二、入门指南
- - 1、提议新功能
  - 2、问题报告
  - 3、功能实现与缺陷修复
  - 4、添加教程
  - 5、改进文档与教程
  - 6、参与在线讨论
  - 7、通过 PR 修复问题
  - 8、审查开放 PR
  - 9、提升代码可读性
  - 10、增强测试覆盖
  - 11、推广 PyTorch
  - 12、问题分类
- 三、开源开发须知
- 四、避免常见错误
- 五、常见问题解答
- 六、文档体系
- - 1、Python 文档
  - 2、C++ 文档
- 七、教程系统
- - 1、教程构建流程
  - 2、贡献新教程
PyTorch 设计哲学
- 一、设计原则
- - 1、可用性优先于性能
  - 2、简单优于便捷
  - 3、Python 优先与顶尖语言互操作性
PyTorch 治理机制
- 一、概述
- 二、模块维护者
- 三、核心维护者
- 四、首席核心维护者 (BDFL)
- 五、维护者提名与任免机制
- - 1、基本原则
  - 2、提名流程
  - 3、移除流程
  - 4、首席维护者更替
- 六、模块管理机制
- 七、决策机制
- - 1、常规变更
  - 2、争议性变更
  - 3、项目政策
- 八、常见问题

PyTorch 治理体系 | 构建与持续集成

一、如何新增维护者

候选人需满足以下条件才能成为维护者：

至少向 PyTorch 代码库相关部分提交过 6 次 commit
其中至少 1 次 commit 是在最近 6 个月内提交的

要为合格候选人添加维护者权限，需执行以下操作：
1、创建 PR 将候选人添加至核心贡献者名单页面
2、同步更新合并规则文件
现有维护者将通过投票表决，PR 合并的决策标准如下：

必须等待至少 2 个工作日后再合并（确保大多数贡献者已查看）
PR 需正确标记 module: ci 标签
现有维护者无人提出反对意见
获得至少 3 个净赞成票（若该模块维护者少于 3 人，则需全体维护者赞成）

PyTorch 贡献指南

注意：本页面已弃用。请参考 PyTorch Wiki 上的贡献指南。

PyTorch 是一个基于磁带自动微分系统的 GPU 加速 Python 张量计算库，用于构建深度神经网络。

一、贡献流程

PyTorch 组织遵循 PyTorch 治理章程，技术贡献指南详见 CONTRIBUTING.md。

PyTorch 的开发过程包含核心开发团队与社区之间的大量公开讨论。虽然 PyTorch 的 GitHub 工作流程与大多数开源项目类似，但如果你是首次贡献开源项目，以下是基本流程：

确定工作内容
大多数开源贡献源于开发者解决自身需求。若你尚未明确目标或希望熟悉项目，可通过以下方式寻找合适任务：
- 查阅 issue 跟踪器，寻找可修复的问题。被其他贡献者确认的问题通常更值得关注。我们为新手保留了特定标签（如 bootcamp 和 1hr），但这些标签维护频率较低。
- 加入开发讨论区告知你的意向。我们非常乐意帮助研究者和合作伙伴熟悉代码库。
评估变更范围
对于小型变更可直接实施，大型变更建议先通过提交 RFC 获取设计意见：
- 不确定变更规模？可在 issues 或开发讨论区咨询。
- 标准化功能（如新增算子或优化器）需提供效用证明（如论文引用或其他框架实现）。
  - 近期研究成果的算子/算法 通常不被接受，除非有压倒性证据表明其突破性价值。不确定时可先创建 issue 讨论。
- 核心变更需特别注意协调，因主分支开发节奏极快。基础性改动建议分阶段实施。
编写代码
技术实现建议参考 CONTRIBUTING.md。
提交 Pull Request
- 未完成时创建 Draft PR 或添加 “[WIP]” 前缀。复杂变更建议始终以 Draft 状态启动，便于持续集成测试。
- 为 PR 指定合适审查者。可参考核心维护者列表直接@相关人员。
迭代优化直至合并
- 我们将尽量减少审查轮次，仅对重大问题提出阻塞意见。常见问题参考避免常见错误章节。
- PR 通过审查且 CI 测试通过后，我们将自动完成合并。

二、入门指南

1、提议新功能

新功能建议应在特定 issue 中讨论。请尽可能提供详细信息、配套数据及解决方案。PyTorch 团队和社区会定期审查新 issue 并提供帮助。若方案成熟可直接实现。

2、问题报告

发现问题时请先搜索现有 issue 列表。确认无类似问题后新建 issue，需包含：

问题重现步骤
预期行为说明
相关环境信息

3、功能实现与缺陷修复

修复特定 issue 时建议先在对应 issue 中留言说明意图。除合作开发者外，我们通常不会锁定或分配 issue。最佳实践是与团队讨论方案，可节省大量时间。

标有 first-new-issue、low 或 medium 优先级的 issue 最适合新手入门。

4、添加教程

pytorch.org 上多数教程来自社区贡献。新增教程请参考：PyTorch 教程贡献指南

5、改进文档与教程

我们致力于提供高质量文档。若发现拼写错误或内容缺陷，欢迎提交 PR。文档系统说明详见文档体系章节。

6、参与在线讨论

开发者可加入：

用户讨论区：PyTorch Discussion Forums
核心开发讨论区：PyTorch Dev Discussion Forums

7、通过 PR 修复问题

所有开放 issue 可通过此列表查看。在 issue 中留言说明解决方案能有效吸引团队注意。复杂问题我们会提供具体指导。

8、审查开放 PR

协助审查 PR 始终受欢迎。虽然团队会快速响应并合并有价值提交，但更多审查者能提高代码质量。

9、提升代码可读性

小范围改进优于大范围改动。建议先在论坛或相关 issue 发起讨论。

10、增强测试覆盖

补充测试用例能使代码库更健壮。

11、推广 PyTorch

在研究论文、技术博客或项目中采用 PyTorch 能有效扩大社区影响力。需要市场支持请联系 marketing@pytorch.org。

12、问题分类

若认为某 issue 需要调整标签或优先级，欢迎留言提出建议。

三、开源开发须知

首次贡献者可能对以下流程感到陌生：

无法"认领"issue
开源社区不鼓励独占式认领，因为开发者可能中途放弃。建议以咨询方式沟通，最终以可运行代码和共识推进。
新功能门槛较高
不同于企业环境，合并后的代码将由全体维护者共同负责。这导致我们对合并代码的质量要求更为严格。

四、避免常见错误

缺少测试
测试用例能帮助：
1、检测后续破坏
2、验证初始正确性（如 Knuth 所言：“未运行的代码不可轻信”）
例外情况：极简变更或难以测试的改动需明确说明验证方式。
PR 过大
审查难度与 PR 规模呈非线性增长。大型变更应：
- 提前进行设计讨论
- 拆分为可独立合并的模块
- 提供完整描述
缺少关键注释
复杂逻辑需附加说明文档。
临时解决方案
Hack 代码需特别说明必要性。
修改核心组件
基础组件变更需额外审查，务必提前与团队协调。
新功能开发
务必先在相关 issue 中讨论设计方案。
无关变更
PR 应仅包含直接相关的文件修改。

五、常见问题解答

如何参与审查？
重现问题、测试新功能、协助排查问题均有价值。在 PR 中补充环境细节尤为有用。
CI 测试失败？
可能基于损坏的主分支。尝试 rebase 到最新主分支，或查看 CI 状态：https://hud.pytorch.org/
高风险变更？
构建配置修改风险最高，必须提前讨论。
分支出现陌生提交？
可能是其他贡献者为修复 CI 提供的补丁。

六、文档体系

1、Python 文档

使用 Sphinx 从 Python 源码生成，部署于：

站点：https://pytorch.org/docs
源码：https://github.com/pytorch/pytorch/tree/main/docs
托管：https://github.com/pytorch/pytorch.github.io/tree/master/docs

2、C++ 文档

通过 Doxygen 生成，部署于：

站点：https://pytorch.org/cppdocs
源码：https://github.com/pytorch/pytorch/tree/main/docs/cpp
托管：https://github.com/pytorch/cppdocs

七、教程系统

教程用于指导特定任务或概念理解，通过 Sphinx-Gallery 从 Python 或 RST 文件生成：

站点：https://pytorch.org/tutorials
源码：https://github.com/pytorch/tutorials

1、教程构建流程

PR 触发完整重建：

CircleCI 分 9 个并行任务，耗时约 40 分钟
同步执行 Netlify 快速构建（不渲染 notebook 输出）
合并后通过 GitHub Actions 重新部署

2、贡献新教程

参考：PyTorch 教程贡献指南

PyTorch 设计哲学

https://docs.pytorch.org/docs/stable/community/design.html

本文档旨在帮助贡献者和模块维护者理解 PyTorch 长期发展形成的高层设计原则。这些原则并非铁律，而是作为权衡不同关注点和解决开发过程中可能出现的分歧的指南。有关贡献、模块维护以及如何向核心维护者提请争议解决的更多信息，请参阅 PyTorch 治理文档。

一、设计原则

1、可用性优先于性能

这一原则可能令人惊讶！正如某位 Hacker News 用户所言：PyTorch 太棒了！[…] 但令我困惑的是，一个机器学习框架怎么能不痴迷于速度/性能？ 参见 Hacker News 关于 PyTorch 的讨论。

Soumith 在《壮大 PyTorch 社区》博文中深入探讨了这一点，其核心观点是：

PyTorch 的首要目标是可用性
次要目标是保持合理的性能

我们认为，保持灵活性以支持基于我们抽象层开展研究的人员至关重要。虽然无法预知未来的工作负载形态，但我们希望这些工作负载能首先在 PyTorch 上构建——这需要框架具备足够的灵活性。

具体而言，我们采用可用性优先的工作方式，避免在未充分权衡利弊的情况下贸然采用限制优先的方案（例如静态形状、纯图模式等）。虽然预先施加严格的用户限制可以简化实现，但存在以下风险：

性能收益可能无法抵消用户摩擦，要么因为性能提升不够显著，要么仅适用于相对狭窄的子问题集
即使性能收益显著，这些限制可能导致生态系统分裂成具有不同限制条件的子集，最终令用户难以理解

我们希望用户能够无缝地将 PyTorch 代码迁移到不同的硬件和软件平台，与各类库和框架互操作，并体验完整的 PyTorch 用户体验，而非最低公分母的功能子集。

2、简单优于便捷

此处我们借鉴了《Python 之禅》的理念：

显式优于隐式
简单优于复杂

更简洁的表述是《简单与容易》中的观点。让我们通过示例说明，因为在日常英语中*简单(simple)和容易(easy)*常被混用。以 PyTorch 中设备的建模方式为例：

简单/显式（便于理解、调试）： 每个张量都关联特定设备。用户需显式指定张量设备迁移。跨设备操作会直接报错
便捷/隐式（易于使用）： 用户无需关心设备，系统会自动确定全局最优设备布局

在这个具体案例以及整体设计哲学中，PyTorch 倾向于提供简单显式的构建块，而非面向从业者的便捷 API。简单版本能让新用户立即理解并调试：当程序执行到实际调用跨设备操作的代码位置时，你会获得明确的错误提示。便捷方案或许能让新用户快速上手，但调试这类系统可能变得复杂：系统如何做出决策？接入该系统的 API 是什么？其中间表示(IR)中的对象如何表达？

支持这种设计的经典论述来自《分布式计算笔记》（核心观点：不要用统一方式建模性能特征差异巨大的资源，细节终将暴露）和《端到端原则》（核心观点：在底层堆栈构建智能机制会阻碍高层堆栈开发高性能特性，且往往徒劳无功）。例如，我们可以制定算子级或全局设备迁移规则，但精确选择并不明显，而构建可扩展机制必然带来复杂性和延迟成本。

需要说明的是，这并不意味着高层"便捷"API 没有价值。显然，在堆栈高层支持跨异构计算集群的高效张量运算具有重要价值。我们的核心观点是：聚焦简单的底层构建块既能指导便捷 API 的设计，又能确保用户在偏离常规路径时仍获得良好体验。这也为创新留出空间，使得更具倾向性的工具能以 PyTorch 核心库无法支持的速度发展——正如我们丰富的生态系统所证明的，这种模式最终会反哺核心库。换言之，初始阶段不盲目自动化，反而可能让我们更快达到理想的自动化水平。

3、Python 优先与顶尖语言互操作性

这一原则最初表述为Python 优先：

PyTorch 不是封装在单体 C++ 框架外的 Python 绑定。它被设计为深度集成到 Python 生态中。你可以像使用 NumPy、SciPy 或 scikit-learn 等 Python 库那样自然地使用它。你可以直接用 Python 编写新的神经网络层，调用喜爱的库，并使用 Cython 和 Numba 等工具包。我们的目标是在适当场景避免重复造轮子。

多年来 PyTorch 一直在应对 Python 开销问题：我们首先用 C++ 重写了自动微分引擎，然后迁移了大部分算子定义，随后开发了 TorchScript 和 C++ 前端。

尽管如此，Python 仍为用户提供了最佳体验：灵活、熟悉，最重要的是拥有庞大的科学计算库和扩展生态系统。这一事实推动了我们最近的几项重要贡献，它们试图在接近 Python 可用性曲线的帕累托最优点上取得突破：

TorchDynamo：能通过最小用户干预加速现有即时模式 PyTorch 程序的 Python 帧评估工具
torch_function 和 torch_dispatch 扩展点：支持在 C++ 内部实现基础上构建 Python 优先的功能，例如分别催生了 torch.fx 追踪器和 functorch

这些设计原则并非铁律，而是历经实践检验的选择，它们锚定了 PyTorch 成为如今这个可调试、可扩展且灵活的框架的发展轨迹。随着贡献者和维护者群体的壮大，我们期待与您共同在库和生态系统中践行这些核心原则。我们也保持开放态度，随着认知深化和 AI 领域演进，持续迭代这些原则——因为我们深知，变革永不止息。