在使用 AI-Toolkit 進行模型訓練時，最令人沮喪的莫過於原本運作正常的環境突然啟動了動輒數十 GB 的模型下載。這次的經驗起源於一次訓練過程中的手動中斷，這看似平凡的操作卻觸發了 Hugging Face 快取機制的連鎖反應。由於中斷可能導致本地快取索引與遠端倉庫的雜湊值（Hash）出現不匹配，加上環境中未安裝 hf_xet 套件，系統在無法進行高效校驗的情況下，自動回退到最保守的 HTTP 下載模式，試圖重新抓取整個 Z-Image-Turbo 模型。這不僅浪費頻寬，更揭示了對自動化管理工具過度依賴的風險。
為了一勞永逸地解決這個問題，將模型從隱蔽的系統快取資料夾（.cache/huggingface/hub）提取至自定義路徑是必要的步驟。在搬遷過程中，存儲介質的選擇展現了極大的性能差異。起初嘗試將模型放置於 D 槽的機械硬碟（HDD），雖然空間充裕，但其讀取延遲明顯拖慢了載入速度；隨後改為搬遷至 C 槽的 SSD 路徑（如 C:\ai-models），模型的加載時間大幅縮短，這對於高效能硬體配備來說，能有效移除 I/O 瓶頸，讓訓練啟動更為順暢。
在設定檔（YAML）的撰寫上，絕對路徑的使用必須非常精確，尤其是 Windows 環境下的轉義字元問題。將 name_or_path 指向基礎模型資料夾時，程式能自動掃描內部組件，但在設定 assistant_lora_path 時則存在一個關鍵陷阱：程式預期的是一個精確的檔案路徑而非資料夾。若僅指向資料夾，系統會拋出 FileNotFoundError 錯誤。以下整理了此次環境優化前後的設定對比與關鍵參數：
| 優化項目 | 調整前 (自動模式) | 調整後 (手動優化) |
|---|---|---|
| 模型讀取來源 | Hugging Face 線上同步 | 本地絕對路徑 (C:\ai-models) |
| 存儲介質效能 | 系統碟預設路徑 | 可自行決定存放位置 |
| 連網行為 | 每次啟動校驗 (易出錯) | 直接使用離線模型檔 |
| Adapter 路徑 | 指向 snapshots 資料夾 | 精確指向 .safetensors 檔案 |
最後，透過在 YAML 中將模型取用路徑寫上，我們成功構建了一個穩定且高效的訓練環境。這不僅讓 LoRA 訓練能快速迭代，也避免了未來因網路波動或快取毀損導致的無謂等待。此次經驗證明，深度理解工具的底層載入邏輯與硬體瓶頸，是提升 AI 訓練效率不可或缺的基本功。
實際操作流程
一、模型檔案提取與路徑規劃
首先，必須將模型從 Hugging Face 隱藏的快取目錄中提取出來。請前往 C:\Users\[您的使用者名稱]\.cache\huggingface\hub 尋找對應模型（像是 models--Tongyi-MAI--Z-Image-Turbo 和 models--ostris--zimage_turbo_training_adapter）的 snapshots 資料夾。建議在 SSD（如 C 槽）建立一個專屬資料夾 C:\ai-models，並將 Z-Image-Turbo 的核心組件（包含 transformer、vae、tokenizer 等）與 Training Adapter 權重檔案分別複製進去。完成搬遷後的檔案結構如下：
C:\ai-models
├─Z-Image-Turbo
│ ├─text_encoder
│ │ config.json
│ │ generation_config.json
│ │ model-00001-of-00003.safetensors
│ │ model-00002-of-00003.safetensors
│ │ model-00003-of-00003.safetensors
│ │ model.safetensors.index.json
│ │
│ ├─tokenizer
│ │ merges.txt
│ │ tokenizer.json
│ │ tokenizer_config.json
│ │ vocab.json
│ │
│ ├─transformer
│ │ config.json
│ │ diffusion_pytorch_model-00001-of-00003.safetensors
│ │ diffusion_pytorch_model-00002-of-00003.safetensors
│ │ diffusion_pytorch_model-00003-of-00003.safetensors
│ │ diffusion_pytorch_model.safetensors.index.json
│ │
│ └─vae
│ config.json
│ diffusion_pytorch_model.safetensors
│
└─zimage_turbo_training_adapter
zimage_turbo_training_adapter_v2.safetensors二、精確配置 YAML 設定檔路徑
在修改 AI-Toolkit 的 .yaml 設定檔時，必須區分「資料夾路徑」與「實體檔案路徑」的差異。基礎模型 name_or_path 應指向資料夾，而 assistant_lora_path 則必須精確指向 .safetensors 檔案本體，否則會觸發 FileNotFoundError。此外，在 Windows 環境下建議使用雙反斜線 \ 以確保路徑解析正確。優化後的 YAML 設定範例：
model:
name_or_path: "C:\\ai-models\\Z-Image-Turbo"
quantize: true
qtype: "qfloat8"
arch: "zimage:turbo"
low_vram: true
assistant_lora_path: "C:\\ai-models\\zimage_turbo_training_adapter\\zimage_turbo_training_adapter_v2.safetensors"
《上一篇》Flow：運用 Google 推出的 AI 影片生成平台體驗 Veo 3 
留言區 / Comments
萌芽論壇