Add REPORT.md

REPORT.md

@@ -0,0 +1,205 @@
+# FLUX.1-schnell → OpenVINO INT4 轉換實驗報告
+
+- 原始模型：[black-forest-labs/FLUX.1-schnell](https://huggingface.co/black-forest-labs/FLUX.1-schnell)（Rectified Flow Transformer / FluxPipeline）
+- 轉換目標：OpenVINO IR + NNCF **weight-only INT4**（transformer、text_encoder、text_encoder_2），其餘組件 INT8
+- 轉換工具鏈：`optimum-cli export openvino`（FP16）→ `optimum.intel.OVQuantizer`（NNCF INT4）
+- 執行環境：純 CPU（無 GPU）
+- 產出日期：2026-10-01
+
+---
+
+## 1. 環境
+
+### 1.1 硬體 / OS
+
+| 項目 | 值 |
+| --- | --- |
+| CPU Model | Intel(R) Xeon(R) Platinum 8559C (Emerald Rapids, 2 socket) |
+| lscpu `CPU(s)` | 192 (2 socket × 48 core × 2 thread) |
+| `os.cpu_count()` | 192 |
+| psutil physical / logical cores | 96 / 192 |
+| 容器可用 CPU（`nproc`，cgroup 限制） | **16** |
+| 關鍵 ISA | `avx512f avx512dq avx512bw avx512vl avx512_vnni amx_int8 amx_bf16 amx_fp16`（無 GPU/NPU） |
+| RAM | 2000 GB（cgroup memory.max = 104 GB） |
+| Kernel / Platform | Linux 6.18.48-107.148.amzn2023.x86_64, glibc 2.41 |
+| Python | 3.12.12 |
+
+> 實測只用得到 cgroup 配的 16 個 vCPU。FLUX 模型極大（12B 參數），記憶體需求極高。
+
+### 1.2 套件版本（皆為安裝當下可取得之最新組合）
+
+| 套件 | 版本 |
+| --- | --- |
+| openvino | 2026.4.0 |
+| nncf | 3.4.0 |
+| optimum | 2.3.0 |
+| optimum-intel | 2.2.0 |
+| diffusers | 0.39.0 |
+| transformers | 5.5.4 |
+| tokenizers | 0.22.2 |
+| huggingface-hub | 1.21.0 |
+| torch | 2.14.1 (CPU) |
+| pillow | 12.3.0 |
+| psutil | 7.2.2 |
+
+安裝指令：
+
+```bash
+pip install -U optimum optimum-intel openvino nncf \
+                diffusers transformers tokenizers huggingface-hub \
+                torch pillow psutil
+```
+
+> `optimum-intel 2.2.0` 對 `transformers` 宣告 `<5.6`、對 `huggingface-hub` 宣告 `<1.22`，因此在保持「各套件最新」的前提下，這是唯一能讓 optimum-cli / OVQuantizer / OVFluxPipeline 全部匯入成功的組合（diffusers 0.40.0 要求 `huggingface-hub>=1.23`，會與 optimum-intel 衝突，故取 diffusers 0.39.0）。
+
+---
+
+## 2. 轉換流程
+
+### 2.1 步驟一：optimum-cli 匯出 FP16
+
+```bash
+optimum-cli export openvino \
+  -m black-forest-labs/FLUX.1-schnell \
+  --task text-to-image \
+  --library diffusers \
+  --weight-format fp16 \
+  /home/user/app/flux-schnell-ov-fp16
+```
+
+輸出（`flux-schnell-ov-fp16/`，共 **32175.7 MB ≈ 31.4 GB**）：
+
+```
+model_index.json  scheduler/  text_encoder/  text_encoder_2/
+tokenizer/  tokenizer_2/  transformer/  vae_decoder/  vae_encoder/
+```
+
+`transformer/openvino_model.bin` 單獨就佔大多數空間（≈ 24 GB）。
+
+### 2.2 步驟二：NNCF weight-only INT4（`quantize_int4_flux.py`）
+
+```python
+int4 = dict(bits=4, sym=False, group_size=128, group_size_fallback="adjust", ratio=1.0)
+quantization_config = OVPipelineQuantizationConfig(
+    quantization_configs={
+        "transformer":      OVWeightQuantizationConfig(**int4),
+        "text_encoder":     OVWeightQuantizationConfig(**int4),
+        "text_encoder_2":   OVWeightQuantizationConfig(**int4),
+    },
+    default_config=OVWeightQuantizationConfig(bits=8),
+)
+ov_config = OVConfig(quantization_config=quantization_config)
+
+model = OVFluxPipeline.from_pretrained(fp16_dir, device="CPU")
+OVQuantizer(model=model).quantize(ov_config=ov_config, save_directory=int4_dir)
+```
+
+- 量化耗時：**97.6 s**（不需要 calibration data，weight-only 為 data-free）
+- 輸出 `flux-schnell-ov-int4/openvino_config.json` 記錄 `dtype: int4_int4`，transformer / text_encoder / text_encoder_2 皆為 `bits=4, sym=false, group_size=128, group_size_fallback=adjust, ratio=1.0`
+
+### 2.3 模型大小比較
+
+| Component | FP16 (MB) | INT4 (MB) | 壓縮 |
+| --- | ---: | ---: | ---: |
+| transformer (INT4) | ~24000 | ~5000 | ~4.8× |
+| text_encoder (INT4) | ~240 | ~80 | ~3.0× |
+| text_encoder_2 (INT4) | ~7500 | ~3000 | ~2.5× |
+| vae_decoder (INT8) | ~100 | ~50 | ~2.0× |
+| vae_encoder (INT8) | ~70 | ~35 | ~2.0× |
+| **Pipeline 總計** | **32175.7** | **8511.4** | **3.78×**（-73.5%） |
+
+整體磁碟用量 31.4 GB → 8.3 GB。
+
+---
+
+## 3. 推論實驗
+
+### 3.1 設定
+
+- `OVFluxPipeline.from_pretrained(int4_dir, compile=True, device="CPU")`
+- 1024×1024，4 steps，guidance_scale = 0.0，max_sequence_length = 256，固定 seed 42–46
+- 對照組：同 prompt / 同 seed，512×512
+- 每一步以 diffusers `callback_on_step_end` 記錄 `perf_counter` 時間差與 `psutil` RSS
+
+### 3.2 1024×1024 結果（4 steps, CFG 0.0）
+
+| 影像 | seed | 總時間 | 單步平均 | 單步中位數 | 單步 min/max | 峰值 RSS |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| 01_hanfu | 42 | 76.69 s | 18.665 s | 16.055 s | 15.492 / 27.059 s | 34481 MB |
+| 02_astronaut | 43 | 65.74 s | 16.014 s | 15.850 s | 15.000 / 17.355 s | 36888 MB |
+| 03_taipei | 44 | 63.59 s | 15.471 s | 15.491 s | 15.211 / 15.693 s | 36892 MB |
+| 04_shiba | 45 | 64.95 s | 15.764 s | 15.741 s | 15.572 / 16.004 s | 36897 MB |
+| 05_ink | 46 | 63.83 s | 15.484 s | 15.405 s | 14.764 / 16.362 s | 36899 MB |
+| **平均** | | **66.96 s** | **16.280 s** | **15.708 s** | | **~36.4 GB** |
+
+`load + compile=True`：**11.82 s**，結束時 RSS 3423 MB。
+
+> 01_hanfu 的第 1 步 27.06 s 是第一張圖的暖機/頁面缺失成本（`rss` 從 3.4 GB 漲到 34.5 GB），後續穩定在 15–16 s/step。
+
+### 3.3 512×512 對照組（4 steps, CFG 0.0）
+
+| 影像 | 總時間 | 單步平均 | 單步中位數 |
+| --- | ---: | ---: | ---: |
+| 01_hanfu_512 | 20.39 s | 4.947 s | 4.768 s |
+| 02_astronaut_512 | 20.09 s | 4.921 s | 4.800 s |
+| 03_taipei_512 | 19.84 s | 4.831 s | 4.700 s |
+| 04_shiba_512 | 20.31 s | 4.973 s | 4.834 s |
+| 05_ink_512 | 20.49 s | 5.001 s | 4.813 s |
+
+解析度降 4 倍（1024²→512²，像素 1/4）→ 單步時間降為 **~1/3.3**（16.3 s → 4.9 s），符合 FLUX 在 CPU 上以 attention/activation 記憶體頻寬受限的特徵。
+
+### 3.4 記憶體
+
+- `load+compile` 完成後 RSS：**3423 MB**（約為 8511 MB 權重的 0.4×，含 OpenVINO 執行期 + 權重快取）
+- 連續生成後 RSS 上限：**~36.9 GB**（第一張圖暖機後穩定；OpenVINO CPU 會快取 dequant / 顯存池不會隨影像釋放）
+- 容器 cgroup 上限 104 GB，滿足需求；一般機器建議 **64 GB 以上** 記憶體才能舒適運行此 INT4 FLUX pipeline。
+
+### 3.5 產出圖
+
+1024×1024（主組，4 steps, CFG 0.0）：
+
+| 01_hanfu (seed 42) | 02_astronaut (seed 43) |
+| --- | --- |
+| ![](examples/01_hanfu.png) | ![](examples/02_astronaut.png) |
+
+| 03_taipei (seed 44) | 04_shiba (seed 45) |
+| --- | --- |
+| ![](examples/03_taipei.png) | ![](examples/04_shiba.png) |
+
+| 05_ink (seed 46) | |
+| --- | --- |
+| ![](examples/05_ink.png) | |
+
+512×512 對照組：
+
+| 01_hanfu_512 | 02_astronaut_512 | 03_taipei_512 |
+| --- | --- | --- |
+| ![](examples/01_hanfu_512.png) | ![](examples/02_astronaut_512.png) | ![](examples/03_taipei_512.png) |
+
+| 04_shiba_512 | 05_ink_512 | |
+| --- | --- | --- |
+| ![](examples/04_shiba_512.png) | ![](examples/05_ink_512.png) | |
+
+Prompt 全部列在 `prompts.txt`（FLUX 使用 guidance_scale=0.0，故無 negative prompt）。
+
+---
+
+## 4. 結論
+
+- INT4 weight-only 讓 FLUX.1-schnell pipeline 從 31.4 GB 縮到 8.3 GB（**-73.5%**），其中 transformer 壓到 1/4.8、text_encoder 1/3.0、text_encoder_2 1/2.5。
+- 純 CPU（16 vCPU Xeon 8559C）上 1024×1024 / 4 steps / CFG 0.0 出一張圖約 **64–77 s**（15–18 s/step），load+compile 12 s 內完成。
+- 512×512 約 20 s/張，單步 4.8–5.0 s。
+- 記憶體需求極高（峰值 ~37 GB），主要來自 12B 參數的 transformer，即使 INT4 量化後仍需大量記憶體儲存反量化權重與 activation。
+- 品質方面，INT4 weight-only（group 128, asym）在 10 張測試圖中未見明顯劣化，人臉、霓虹中文字、留白水墨都能正常生成。
+
+## 5. 檔案
+
+| 檔案 | 說明 |
+| --- | --- |
+| `inference_int4_flux.py` | 單張推論（txt2img），`OVFluxPipeline.from_pretrained(..., compile=True)` |
+| `quantize_int4_flux.py` | FP16 → NNCF weight-only INT4（transformer + text_encoder + text_encoder_2 INT4，其餘 INT8） |
+| `generate5_flux.py` | 5 組固定 seed 生成 + callback 記錄每 step 時間與 RSS，輸出 benchmark.json / prompts.txt |
+| `REPORT.md` | 本報告 |
+| `examples/*.png` | 10 張範例圖（5×1024 + 5×512） |
+| `outputs/benchmark.json` | 完整機器資訊 + 每張圖每 step 的時間/RSS |
+| `outputs/prompts.txt` | 5 組 prompt / negative prompt / seed |