diffusion-pipe：擴散模型的管線並行訓練腳本

diffusion-pipe：腳本定位與模型支援

diffusion-pipe 是一個用於擴散模型訓練的管線並行訓練腳本，以 Python 撰寫。README 首行將其描述為「A pipeline parallel training script for diffusion models.」。該腳本依賴 DeepSpeed 的管線並行機制，目標是在單卡顯存無法容納完整模型時，將模型拆分到多張 GPU 上進行訓練。當前 README 列出的模型支援清單包括 SDXL、Flux、LTX-Video、HunyuanVideo（t2v）、Cosmos、Lumina Image 2.0、Wan2.1（t2v 和 i2v）、Chroma、HiDream、Stable Diffusion 3、Cosmos-Predict2、OmniGen2、Flux Kontext、Wan2.2、Qwen-Image、Qwen-Image-Edit、HunyuanImage-2.1、AuraFlow、Z-Image、HunyuanVideo-1.5、Flux 2（Dev 和 Klein）、Anima、Ernie-Image、LTX 2.3、Ideogram4 和 Krea 2。README 沒有提供這些模型的訓練結果或效能比較，也沒有基準測試數據，因此本文不對此做任何推斷。（diffusion-pipe 1-1）

在 tdrussell/diffusion-pipe 的脈絡中，這一節只能由 README 已列出的入口來核對。請以 tdrussell/diffusion-pipe 的 README、main 分支內容與 releases 頁面確認版本，再保留實際命令輸出、設定鍵和錯誤訊息。素材未說明的效能、相容性、故障恢復或安全保證，不應從專案描述、star 數或單一範例推導。若要驗證本節，應選取一個與 diffusion-pipe 直接相關的最小輸入，觀察輸出檔案、API 回應或終端日誌，並把成功與失敗結果分開記錄。（章節 1）

tdrussell/diffusion-pipe 第 1 節的入口還要和相鄰章節分開看：diffusion-pipe README 明確寫出的命令、檔名或 API 只支持它所描述的範圍。執行時應保存輸入內容、程式版本和輸出結果，遇到錯誤則記錄完整訊息，不把一次成功執行延伸成所有平台都能成功。

tdrussell/diffusion-pipe 第 1 節的採用邊界，取決於 README 具體列出的版本與執行條件。測試時先檢查 diffusion-pipe 的安裝入口是否成功，再逐項比對輸入、輸出和日誌；若需要外部服務、容器、憑證或特定作業系統，應把該條件寫入紀錄。diffusion-pipe README 沒有描述的行為仍屬未知，不能用相似工具的經驗代替。

diffusion-pipe：安裝與依賴處理

安裝流程從複製倉庫開始，README 給出的命令是 git clone --recurse-submodules https://github.com/tdrussell/diffusion-pipe，因為倉庫包含 ComfyUI 子模組。如果複製時沒有使用 --recurse-submodules，則需要隨後執行 git submodule init 和 git submodule update。環境方面，README 建議使用 Miniconda 建立 Python 3.12 環境，並先安裝 PyTorch，再安裝 requirements.txt 中的其餘依賴。PyTorch 不在 requirements 檔案中，因為不同 GPU 可能需要不同的 PyTorch 或 CUDA 版本。README 還提到 Flash Attention 為可選依賴，部分模型需要；而 Cosmos 原始模型額外需要 TransformerEngine，並提供了一個帶環境變數的安裝命令範例。這些命令均以 README 原文為準，未在 README 中出現的安裝組合不應被當作通用建議。（diffusion-pipe 2-1）

在 tdrussell/diffusion-pipe 的脈絡中，這一節只能由 README 已列出的入口來核對。請以 tdrussell/diffusion-pipe 的 README、main 分支內容與 releases 頁面確認版本，再保留實際命令輸出、設定鍵和錯誤訊息。素材未說明的效能、相容性、故障恢復或安全保證，不應從專案描述、star 數或單一範例推導。若要驗證本節，應選取一個與 diffusion-pipe 直接相關的最小輸入，觀察輸出檔案、API 回應或終端日誌，並把成功與失敗結果分開記錄。（章節 2）

tdrussell/diffusion-pipe 第 2 節的入口還要和相鄰章節分開看：diffusion-pipe README 明確寫出的命令、檔名或 API 只支持它所描述的範圍。執行時應保存輸入內容、程式版本和輸出結果，遇到錯誤則記錄完整訊息，不把一次成功執行延伸成所有平台都能成功。

tdrussell/diffusion-pipe 第 2 節的採用邊界，取決於 README 具體列出的版本與執行條件。測試時先檢查 diffusion-pipe 的安裝入口是否成功，再逐項比對輸入、輸出和日誌；若需要外部服務、容器、憑證或特定作業系統，應把該條件寫入紀錄。diffusion-pipe README 沒有描述的行為仍屬未知，不能用相似工具的經驗代替。

diffusion-pipe：資料集準備與快取機制

資料集由一個或多個目錄組成，目錄內包含影像或影片檔案及對應的 .txt 字幕檔案。媒體檔案與字幕檔案需要同名，例如 image1.png 對應 image1.txt；若缺少字幕檔案，訓練會繼續但使用空字幕。影像格式方面，README 說明任何 Pillow 能載入的格式都應可用；影片格式方面，任何 ImageIO 能載入的格式都應可用，但 WebP 影片不被支援，因為 ImageIO 無法載入多幀 WebP。訓練前，latents 和 text embeddings 會被快取到磁碟，快取目錄位於每個資料集目錄下的 cache 資料夾中。快取使用 Huggingface Datasets 庫實現，並在多次訓練運行之間重用。相關命令列參數包括 --cache_only（只執行快取流程後退出）、--regenerate_cache（強制重新生成快取）和 --trust_cache（不檢查檔案是否變化而直接載入快取元資料，適用於 100,000 張以上影像的大型資料集）。由於 text encoders 的快取機制，README 明確指出目前不支援為 text encoders 訓練 LoRA。（diffusion-pipe 3-1）

在 tdrussell/diffusion-pipe 的脈絡中，這一節只能由 README 已列出的入口來核對。請以 tdrussell/diffusion-pipe 的 README、main 分支內容與 releases 頁面確認版本，再保留實際命令輸出、設定鍵和錯誤訊息。素材未說明的效能、相容性、故障恢復或安全保證，不應從專案描述、star 數或單一範例推導。若要驗證本節，應選取一個與 diffusion-pipe 直接相關的最小輸入，觀察輸出檔案、API 回應或終端日誌，並把成功與失敗結果分開記錄。（章節 3）

tdrussell/diffusion-pipe 第 3 節的入口還要和相鄰章節分開看：diffusion-pipe README 明確寫出的命令、檔名或 API 只支持它所描述的範圍。執行時應保存輸入內容、程式版本和輸出結果，遇到錯誤則記錄完整訊息，不把一次成功執行延伸成所有平台都能成功。

tdrussell/diffusion-pipe 第 3 節的採用邊界，取決於 README 具體列出的版本與執行條件。測試時先檢查 diffusion-pipe 的安裝入口是否成功，再逐項比對輸入、輸出和日誌；若需要外部服務、容器、憑證或特定作業系統，應把該條件寫入紀錄。diffusion-pipe README 沒有描述的行為仍屬未知，不能用相似工具的經驗代替。

diffusion-pipe：訓練啟動與設定範例

README 建議先閱讀 examples 目錄中的設定檔，尤其是 main_example.toml 和 dataset.toml。前者包含主要的註解說明，後者包含資料集選項的文件。使用者需要複製設定檔並至少修改所有路徑，包括資料集設定檔中的路徑。訓練啟動命令在 README 中的範例為：NCCL_P2P_DISABLE="1" NCCL_IB_DISABLE="1" deepspeed --num_gpus=1 train.py --deepspeed --config examples/hunyuan_video.toml。README 特別說明 RTX 4000 系列需要設定這兩個環境變數，其他 GPU 可能不需要。如果啟用了檢查點功能，可以使用 --resume_from_checkpoint 標誌從最新檢查點恢復訓練，也可以在該標誌後指定具體的檢查點資料夾名稱。恢復訓練時使用的是命令列傳入的設定檔，而非輸出目錄中儲存的設定檔，使用者需要自行確保兩者一致。（diffusion-pipe 4-1）

在 tdrussell/diffusion-pipe 的脈絡中，這一節只能由 README 已列出的入口來核對。請以 tdrussell/diffusion-pipe 的 README、main 分支內容與 releases 頁面確認版本，再保留實際命令輸出、設定鍵和錯誤訊息。素材未說明的效能、相容性、故障恢復或安全保證，不應從專案描述、star 數或單一範例推導。若要驗證本節，應選取一個與 diffusion-pipe 直接相關的最小輸入，觀察輸出檔案、API 回應或終端日誌，並把成功與失敗結果分開記錄。（章節 4）

tdrussell/diffusion-pipe 第 4 節的入口還要和相鄰章節分開看：diffusion-pipe README 明確寫出的命令、檔名或 API 只支持它所描述的範圍。執行時應保存輸入內容、程式版本和輸出結果，遇到錯誤則記錄完整訊息，不把一次成功執行延伸成所有平台都能成功。

tdrussell/diffusion-pipe 第 4 節的採用邊界，取決於 README 具體列出的版本與執行條件。測試時先檢查 diffusion-pipe 的安裝入口是否成功，再逐項比對輸入、輸出和日誌；若需要外部服務、容器、憑證或特定作業系統，應把該條件寫入紀錄。diffusion-pipe README 沒有描述的行為仍屬未知，不能用相似工具的經驗代替。

diffusion-pipe：輸出檔案與檢查點結構

每次訓練運行都會在 output_dir 下建立一個新目錄，其中包含檢查點、儲存的模型和 Tensorboard 指標。儲存的模型或 LoRA 位於類似 epoch1、epoch2 的目錄中；DeepSpeed 檢查點位於類似 global_step1234 的目錄中。檢查點包含權重、優化器和資料載入器狀態等全部訓練狀態，但不能直接用於推論。儲存的模型目錄中包含 safetensors 權重、PEFT adapter 設定 JSON 以及 diffusion-pipe 設定檔，後者便於追蹤訓練運行設定。README 沒有說明檢查點檔案的具體格式版本或跨版本相容性，也沒有說明 Tensorboard 指標的具體項目清單。（diffusion-pipe 5-1）

在 tdrussell/diffusion-pipe 的脈絡中，這一節只能由 README 已列出的入口來核對。請以 tdrussell/diffusion-pipe 的 README、main 分支內容與 releases 頁面確認版本，再保留實際命令輸出、設定鍵和錯誤訊息。素材未說明的效能、相容性、故障恢復或安全保證，不應從專案描述、star 數或單一範例推導。若要驗證本節，應選取一個與 diffusion-pipe 直接相關的最小輸入，觀察輸出檔案、API 回應或終端日誌，並把成功與失敗結果分開記錄。（章節 5）

tdrussell/diffusion-pipe 第 5 節的入口還要和相鄰章節分開看：diffusion-pipe README 明確寫出的命令、檔名或 API 只支持它所描述的範圍。執行時應保存輸入內容、程式版本和輸出結果，遇到錯誤則記錄完整訊息，不把一次成功執行延伸成所有平台都能成功。

tdrussell/diffusion-pipe 第 5 節的採用邊界，取決於 README 具體列出的版本與執行條件。測試時先檢查 diffusion-pipe 的安裝入口是否成功，再逐項比對輸入、輸出和日誌；若需要外部服務、容器、憑證或特定作業系統，應把該條件寫入紀錄。diffusion-pipe README 沒有描述的行為仍屬未知，不能用相似工具的經驗代替。

diffusion-pipe：顯存優化與平行策略

為降低顯存需求，README 在 wan_14b_min_vram.toml 範例檔案中集中展示了若干設定，包括使用 AdamW8BitKahan 優化器、啟用 block swapping（範例為 blocks_to_swap = 32）、使用 unsloth activation checkpointing（activation_checkpointing = 'unsloth'）以及設定 PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True。README 提到 expandable_segments 在影片訓練和多種寬高比桶的情況下幫助很大，但也提到在其系統上有時會導致隨機的 CUDA 失敗；如果訓練能通過前幾步，則通常會持續訓練而不失敗。平行策略方面，程式碼使用混合資料平行和管線平行。--num_gpus 標誌控制 GPU 數量，設定中的 pipeline_stages 控制管線平行度，資料平行度會自動設定為使用所有 GPU，因此 GPU 數量必須能被 pipeline_stages 整除。例如，4 張 GPU 且 pipeline_stages=2 時，會執行兩個模型實例，每個實例橫跨兩張 GPU。（diffusion-pipe 6-1）

在 tdrussell/diffusion-pipe 的脈絡中，這一節只能由 README 已列出的入口來核對。請以 tdrussell/diffusion-pipe 的 README、main 分支內容與 releases 頁面確認版本，再保留實際命令輸出、設定鍵和錯誤訊息。素材未說明的效能、相容性、故障恢復或安全保證，不應從專案描述、star 數或單一範例推導。若要驗證本節，應選取一個與 diffusion-pipe 直接相關的最小輸入，觀察輸出檔案、API 回應或終端日誌，並把成功與失敗結果分開記錄。（章節 6）

tdrussell/diffusion-pipe 第 6 節的入口還要和相鄰章節分開看：diffusion-pipe README 明確寫出的命令、檔名或 API 只支持它所描述的範圍。執行時應保存輸入內容、程式版本和輸出結果，遇到錯誤則記錄完整訊息，不把一次成功執行延伸成所有平台都能成功。

tdrussell/diffusion-pipe 第 6 節的採用邊界，取決於 README 具體列出的版本與執行條件。測試時先檢查 diffusion-pipe 的安裝入口是否成功，再逐項比對輸入、輸出和日誌；若需要外部服務、容器、憑證或特定作業系統，應把該條件寫入紀錄。diffusion-pipe README 沒有描述的行為仍屬未知，不能用相似工具的經驗代替。

diffusion-pipe：授權條款與擴充方式

該倉庫使用 GPL-3.0 授權條款。README 中的 Recent changes 提到，2025-11-29 將授權條款改為 GPL-3，以便使用 ComfyUI 程式碼，並說明後續模型實現將盡可能使用 ComfyUI 後端程式碼。GPL-3.0 授權條款文本本身沒有就軟體的安全性、支援或保修作出承諾；該授權條款明確說明沒有保修，但 README 和授權條款摘錄均未涉及具體的安全保證或商業支援。擴充方面，README 在 Features 中說明，新增模型的方式是實作一個子類別。ComfyUI 子模組已新增到倉庫中，因此拉取更新後需要執行 git submodule update。關於 GPL-3.0 對被授權方在散佈或修改程式碼時的具體義務，應以授權條款全文為準。（diffusion-pipe 7-1）

在 tdrussell/diffusion-pipe 的脈絡中，這一節只能由 README 已列出的入口來核對。請以 tdrussell/diffusion-pipe 的 README、main 分支內容與 releases 頁面確認版本，再保留實際命令輸出、設定鍵和錯誤訊息。素材未說明的效能、相容性、故障恢復或安全保證，不應從專案描述、star 數或單一範例推導。若要驗證本節，應選取一個與 diffusion-pipe 直接相關的最小輸入，觀察輸出檔案、API 回應或終端日誌，並把成功與失敗結果分開記錄。（章節 7）

tdrussell/diffusion-pipe 第 7 節的入口還要和相鄰章節分開看：diffusion-pipe README 明確寫出的命令、檔名或 API 只支持它所描述的範圍。執行時應保存輸入內容、程式版本和輸出結果，遇到錯誤則記錄完整訊息，不把一次成功執行延伸成所有平台都能成功。

tdrussell/diffusion-pipe 第 7 節的採用邊界，取決於 README 具體列出的版本與執行條件。測試時先檢查 diffusion-pipe 的安裝入口是否成功，再逐項比對輸入、輸出和日誌；若需要外部服務、容器、憑證或特定作業系統，應把該條件寫入紀錄。diffusion-pipe README 沒有描述的行為仍屬未知，不能用相似工具的經驗代替。

編輯結論

diffusion-pipe 是以 DeepSpeed 管線並行為核心的擴散模型訓練腳本，支援多種影像與影片模型。腳本將快取、檢查點恢復、顯存優化與模型擴展整合在同一套設定中，實際訓練效果仍取決於使用者自身的資料集與硬體組合。 適合能依 tdrussell/diffusion-pipe README 管理相依環境、版本與輸出的人；不適合把 README 的功能清單當成未經條件限制的服務承諾。先執行 README 所列的最小命令或入口，核對 diffusion-pipe 的實際輸入、輸出、錯誤訊息與資料保存位置，再決定是否放入正式工作負載；GPL-3.0 授權下的再發布與修改責任也要由部署者依 LICENSE 原文確認。

官方來源

1. Official README
2. Project repository