为 OpenXLA 做贡献

每个人都可以为 OpenXLA 贡献内容，我们重视每个人的贡献。您可以通过多种方式做出贡献，包括：

  • 在 OpenXLA 的讨论论坛 (openxla-discuss) 上回答问题

  • 改进或扩展 OpenXLA 的文档

  • 为 OpenXLA 的代码库做贡献

  • 以任何上述方式为基于 OpenXLA 构建的更广泛的库生态系统做出贡献

OpenXLA 项目遵循 Google 的开源社区指南。

准备工作

签署贡献者许可协议

对此项目的贡献必须附有贡献者许可协议 (CLA)。您（或您的雇主）保留对您的贡献内容的版权；这只是授予我们许可，允许我们将您的贡献内容用作项目的一部分并重新分发。

如果您或您当前的雇主已签署 Google CLA（即使是针对其他项目签署的），您可能无需再次签署。

访问 <https://cla.developers.google.com/>，查看您当前的协议或签署新协议。

查看《行为准则》

此项目遵循 Tensorflow 的行为准则。

贡献流程

开发者指南

如需有关如何为 OpenXLA 设置开发环境的指南，包括获取代码、构建代码、运行测试和提交更改，请参阅开发者指南。

贡献指南

编译器的架构包含以下组件。

img

优化次数

优化过程会对 HLO 执行转换，以提高计算效率。这些转换涵盖了从与架构无关的高级改进到特定于硬件的调整（例如，针对 NVIDIA GPU 的调整）。

我们通常接受以下内容：
  • 可跨多个工作负载进行泛化，并对性能基准测试产生明显且显著的积极影响的传递。
我们通常会拒绝以下内容：
  • 执行针对特定模型的独特优化的 pass。

Fusion 卡券

融合是一项关键优化措施，可将多个 HLO 操作合并为单个内核，以减少内存 I/O 和内核启动开销。

所有融合传递都应仅添加到融合流水线，而不是之前或之后。这也意味着预优化的 HLO 模块不应包含融合指令。如果融合在流水线中过早形成，就会成为优化传递的障碍。如果融合是在后期形成的，那么我们就无法为生成的融合选择和调整后端。

不允许将自定义调用融合到自定义调用中，即不允许将与生产者/消费者匹配的自定义调用通过模式匹配重写为新的自定义调用。在这种情况下，应将其替换为适当的融合传递。

横向扩缩

对横向扩缩的贡献包括 HLO 优化、成本模型改进、库更新和各种基础设施修改。由于难以重现性能增益，并且内部对多主机配置的需求有限，因此我们坚持严格的验收标准：

我们会优先考虑风险较低的微创变更。

我们通常接受以下内容：

  • 更新了处理 GPU 间或主机间通信的库。

  • 针对新平台的性能表更新。

我们通常会拒绝以下内容：

  • 针对特定模型量身定制的 HLO 重写或运行时更改。

  • 引入新标志、技术债务或回归的基础设施变更。

后端和自动调节

非嵌套运算（例如自定义调用和融合）的后端应实现 CodegenBackend 接口。

此接口对于实现最佳后端选择是必需的，因为它提供了一些方法，可将给定 HLO 指令的参数纳入自动调谐器的搜索空间。

// Returns all supported configs for the given HLO instruction.
virtual absl::StatusOr<std::vector<std::unique_ptr<BackendConfig>>>
  GetSupportedConfigs(const HloInstruction& instr);

// Returns a default config for the given HLO instruction.
virtual absl::StatusOr<std::unique_ptr<BackendConfig>> GetDefaultConfig(
  const HloInstruction& instr);

运行时

XLA 编译流水线的最终结果是一个可以序列化的 thunk 序列。

所有新的 thunk 类型都应该是可序列化的，即 GpuCompiler 或 CpuCompiler 应该能够编译程序并将其序列化，以便 XLA 运行程序稍后可以加载并执行该程序。这意味着不应有指向 HloInstruction 或编译器其他部分或 StreamExecutor 的指针。

代码标准

  • 编码风格：我们遵循 Google 的代码样式指南。 具体请参阅 C/C++ 和 Python 指南。提交的所有代码都必须严格遵守这些样式指南。

  • 紧凑型变更：我们遵循 Google 的工程实践。尤其是，请遵循有关编写紧凑型变更的指南。这样做可以提高可审核性，并降低更改产生意外副作用的可能性，从而大幅提高代码合并速度。即使您要进行大幅更改，也有许多策略可将其分解为更小的增量式更改。

  • 测试覆盖率：所有更改都应包含适当的单元测试。单元测试不应依赖于特定硬件（CPU、GPU 等）的时序，并且应广泛使用模拟对象和伪对象，以实现确定性且重点突出的测试。如果更改旨在扩展当前难以测试的现有代码，则应适当改进可测试性。

    所有更改都应在更改标题中包含适当的基准测试结果，以确保用户清楚了解相关优势。

  • 如果对代码中的惯例有疑问，最好查看现有代码，并尝试遵循 OpenXLA 中已有的模式。

审核流程

所有提交的内容（包括项目成员提交的内容）都需要审核。我们使用 GitHub 拉取请求来实现此目的。如需详细了解如何使用拉取请求，请参阅 GitHub 帮助。

  • 在审核之前，代码必须符合上述所有标准。这些要求并非可选，提交者必须确保其代码符合这些要求，然后才能请求审核，以确保及时接受更改。

  • 所有测试都必须通过。如果您发现某项测试出现问题，但该问题与您的 build 环境或您的更改无关，请与维护人员联系。

  • 在审核过程中，尽量避免范围蔓延。提交者和审核者都有责任确保这一点。如果更改开始变得过大，请考虑将其拆分为多个更改。

  • 在合并更改之前，系统会使用 Google 内部和其他硬件供应商的代码进行内部测试。如果内部测试中出现我们的公共 CI 未捕获到的失败情况，这可能会在审核流程中增加额外的步骤。审核您所做更改的 Google 员工会告知您任何内部测试失败情况，并说明需要修正的问题。

常见问题解答 (FAQ)

XLA 团队没有专门的基础设施团队，因此我们需要共同构建辅助库并避免技术债务。我们认为这是对 XLA 进行更改的常规流程，希望所有人都参与其中。 我们通常会在编写代码时根据需要构建基础架构。

XLA 审核人员可能会要求您在编写 PR 的同时构建一些基础架构（或对 PR 进行其他重大更改）。此请求可能看起来不必要，或者与您尝试进行的更改无关。这可能是因为您对需要构建的基础设施的预期与审核者对同一方面的预期不一致。

预期不符没关系！如果您是项目新手，这是很正常的（有时我们这些老手也会遇到这种情况）。您过去参与的项目可能有着不同的预期。这也是正常现象！这并不意味着这两个项目中的任何一个采用了错误的方法，只是它们的方法不同。我们建议您将基础设施请求与所有其他审核意见一起视为一个机会，了解我们对该项目的期望。

“我可以在未来的 PR 中解决您提出的问题吗？”

对于 PR 中的基础设施请求（或其他大型请求），一个常见的问题是，更改是否必须在原始 PR 中进行，还是可以在未来的 PR 中作为后续操作进行。

一般来说，XLA 不允许 PR 作者通过后续 PR 来处理审核意见。如果审核者认为某个 PR 中存在需要解决的问题，我们通常会要求作者在该 PR 中解决该问题，即使所要求的更改幅度很大也是如此。此标准适用于 Google 外部，也适用于 Google 内部。

XLA 采用这种方法的原因有以下几种。

  • 信任：赢得评价者的信任是一项关键因素。在开源项目中，贡献者可以随时出现或消失。在我们批准 PR 后，审核者无法确保任何承诺的后续工作实际上得到完成。

  • 对其他开发者的影响：如果您已发送触及 XLA 特定部分的 PR，那么很可能其他人也在查看同一部分。如果我们接受 PR 中的技术债务，那么查看此文件的每个人都会受到此债务的影响，直到提交后续 PR 为止。

  • 审核人员带宽：将更改推迟到后续版本会给本已超负荷的审核人员带来多重成本。审核者在等待后续 PR 时可能会忘记第一个 PR 的内容，从而使后续审核更加困难。此外，审核者还必须跟踪预期的后续行动，确保这些行动实际发生。如果可以进行更改，使其与原始 PR 完全正交，以便其他审核者可以审核它，那么带宽问题就不会那么严重。根据我们的经验，这种情况很少见。