為 OpenXLA 貢獻心力

所有人都可為 OpenXLA 貢獻心力，我們也十分重視每位參與者的貢獻。貢獻方式有很多種，包括：

  • 在 OpenXLA 的討論論壇 (openxla-discuss) 上回答問題

  • 改善或擴充 OpenXLA 的說明文件

  • 為 OpenXLA 的程式碼集貢獻心力

  • 以任何上述方式，為建構在 OpenXLA 上的程式庫廣泛生態系統做出貢獻

OpenXLA 專案遵循 Google 開放原始碼社群規範。

事前準備

簽署《貢獻者授權協議》

如要為這個專案貢獻心力，必須附上貢獻者授權協議 (CLA)。您 (或您的雇主) 保留貢獻內容的著作權；這只是授權我們使用及重新發布您的貢獻內容，做為專案的一部分。

如果您或現任雇主已簽署 Google CLA (即使是為了其他專案)，您可能不需要再次簽署。

如要查看現行協議或簽署新協議，請前往 <https://cla.developers.google.com/>。

查看《行為準則》

本專案遵循 Tensorflow 行為準則。

貢獻程序

開發人員指南

如需設定 OpenXLA 開發環境的指南 (包括取得程式碼、建構程式碼、執行測試及提交變更)，請參閱開發人員指南。

貢獻指南

編譯器的架構包含下列元件。

img

最佳化過程

最佳化階段會在 HLO 上執行轉換，以提升運算效率。這些轉換涵蓋的範圍很廣，從與架構無關的高階改良項目，到硬體專屬調整項目 (例如 NVIDIA GPU) 都有。

我們通常會接受下列人士的申訴：
  • 通過多項工作負載的測試，並在效能基準上展現明顯的正面影響。
我們通常會拒絕：
  • 針對特定模型執行獨特最佳化的傳遞。

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 說明。

  • 程式碼必須符合上述所有標準，才能送審。這些並非選用項目，提交者務必先確保程式碼符合規定，再要求審查，才能確保變更及時獲得核准。

  • 所有測試都必須通過。如果發現測試中斷，且問題與建構環境或變更無關，請與維護人員聯絡。

  • 在審查過程中，請盡量避免範圍蔓延。提交者和審查者都有責任確保這點。如果變更開始變得過大，請考慮將其分成多個變更。

  • 變更合併前，會先經過內部測試，測試時會使用 Google 和其他硬體供應商的內部程式碼。如果內部測試失敗，但公開 CI 未偵測到，審查程序可能會增加額外步驟。審查變更的 Google 員工會告知您任何內部測試失敗情形，並說明需要修正的問題。

常見問題 (FAQ)

XLA 團隊沒有專屬的基礎架構團隊，因此我們必須共同建構輔助程式庫，並避免技術債。我們認為這是 XLA 變更的常規程序，所有人都應參與。編寫程式碼時，我們通常會視需要建構基礎架構。

XLA 審查人員可能會要求您建構一些基礎架構 (或對 PR 進行其他重大變更)，連同您撰寫的 PR 一併提交。這項要求可能看似不必要，或與您嘗試進行的變更無關。這可能是因為您對基礎架構建構量的預期，與審查人員的預期不符。

期望不符也沒關係！如果您是專案新手，這很正常 (有時我們這些老手也會遇到這種情況)。您過去參與的專案可能會有不同的期望。這也是正常現象！這並不代表其中一個專案的方法有誤，只是兩者不同。我們建議您將基礎架構要求和所有其他審查意見視為瞭解專案期望的機會。

「我可以在日後的 PR 中處理你的留言嗎？」

在 PR 中，有關基礎架構要求 (或其他大型要求) 的常見問題是：變更是否必須在原始 PR 中進行，還是可以在日後的 PR 中進行後續作業。

一般來說，XLA 不允許 PR 作者透過後續 PR 處理審查意見。如果審查人員認為某個 PR 有需要處理的問題，我們通常會要求作者在該 PR 中解決，即使要求變更的內容很龐大也一樣。這項標準適用於 Google 內外部。

XLA 採取這種做法的原因如下：

  • 信任：贏得審查人員的信任是關鍵要素。在開放原始碼專案中，貢獻者可隨意出現或消失。我們核准 PR 後，審查人員無法確保任何承諾的後續作業確實完成。

  • 對其他開發人員的影響：如果您已傳送觸及 XLA 特定部分的 PR，其他人很可能也會查看相同部分。如果我們接受 PR 中的技術債，則所有查看這個檔案的人都會受到這筆債務影響，直到後續提交為止。

  • 審查人員頻寬：將變更延後至後續追蹤，會對已超負荷的審查人員造成多重成本。審查人員在等待後續 PR 時，可能會忘記第一個 PR 的內容，導致下一次審查更加困難。此外，審查員也必須追蹤預期的後續行動，確保這些行動確實發生。如果變更可以與原始 PR 真正正交，讓其他審查人員審查，頻寬問題就不會那麼嚴重。根據我們的經驗，這種情況很少發生。