samples/README.md

# 換臉效果對比（16 / 8 / 4 bit）

素材為 **NASA 公有領域**太空人官方肖像照片，用同一套程式碼分別跑
**ONNX Runtime FP32（參考）** 與 **OpenVINO fp16 / int8 / int4 / int4-mixed**。

![face montage](20_face_montage.jpg)

## 素材與授權

| 角色 | 檔案 | 來源 |
|---|---|---|
| 來源臉孔 | `input/source_face_nasa_astronaut.jpg` | NASA Johnson Space Center，`jsc2016e096719`（JAXA 太空人 Soichi Noguchi 官方肖像） |
| 目標照片 | `input/target_photo_nasa_astronaut.jpg` | NASA，`jsc2017e063393`（Expedition 54/55 太空人官方肖像） |

* NASA 影像頁面：https://images.nasa.gov/details/jsc2016e096719 、 https://images.nasa.gov/details/jsc2017e063393
* 授權：**公有領域（Public Domain）**，NASA 媒體一般不受版權保護。

## 檔案

| 檔案 | 說明 |
|---|---|
| `00_source_face.jpg` | 來源臉孔對齊後的 128×128 crop |
| `01_target_original_face.jpg` | 目標臉孔（換臉前） |
| `02_target_original.jpg` | 目標照片原圖（1280×1024） |
| `03_onnxruntime_fp32_reference.jpg` | **ONNX Runtime FP32 參考輸出** |
| `40_openvino_fp16.jpg` | OpenVINO fp16（16-bit）輸出 |
| `50_openvino_int8.jpg` | OpenVINO int8（W8A8）輸出 |
| `60_openvino_int4.jpg` | OpenVINO 純 int4（4-bit）輸出 |
| `70_openvino_int4_mixed.jpg` | OpenVINO int4/8 混合精度輸出 |
| `20_face_montage.jpg` | 128×128 換臉結果並排比較 |
| `metrics.json` | 機讀指標 |

## 指標

`PSNR/SSIM` 以 ONNX Runtime FP32（完全相同的預處理與貼回程式碼）為參考；
`embedding cos` 是 OpenVINO ArcFace 算出的來源 embedding 與 FP32 的餘弦相似度。

| 精度 | swapper 大小 | 臉部 PSNR ↑ | 臉部 SSIM ↑ | 全圖 PSNR ↑ | embedding cos ↑ | 單次換臉 ↑ |
|---|---|---|---|---|---|---|
| ONNX Runtime FP32（參考） | 554.3 MB | – | – | – | 1.00000 | 8.08 s |
| fp16 (16-bit) | 276.9 MB | **56.29 dB** | **0.9994** | **71.02 dB** | 1.00000 | 0.47 s |
| int8 (8-bit) | 139.1 MB | 19.28 dB | 0.5557 | 37.09 dB | 0.97941 | **0.09 s** |
| int4-mixed（75% 權重 4-bit） | 91.7 MB | 17.28 dB | 0.6721 | 37.70 dB | 0.94709 | 0.40 s |
| int4（純 4-bit） | **69.7 MB** | 14.79 dB | 0.5317 | 32.29 dB | 0.94709 | 0.43 s |

測試機：Xeon Platinum 8559C（16 vCPU）、OpenVINO 2026.4.1；1280×1024 照片、單張臉。

## 觀察

1. **fp16 與原模型幾乎無差**（56 dB / SSIM 0.9994），速度快 17×，大小減半 → 預設推薦。
2. **int8 最快**（0.09 s，比 ONNX Runtime FP32 快 87×），模型只有原版 1/4；
   臉部有細微顆粒雜訊，但辨識度與膚色都正常。
3. **int4-mixed 是 4-bit 路線的實用點**：膚色正常、沒有明顯色偏，
   在 PSNR 上甚至比 int8 好一點（因為它在活化函數附近保留了 INT8 層），大小 91.7 MB。
4. **純 int4 不可用**：swapper 是類 GAN 網路，4-bit 權重讓膚色整個偏綠/偏橙，
   這點在 montage 右下看得很清楚。若一定要「最小模型 + 可接受品質」，
   請用 `int4-mixed`。
5. `embedding cos` 一欄提醒：**ArcFace 的量化精度會直接影響換到誰的臉**。
   int8 的 cosine 0.979 已足夠安全；用隨機雜訊做校準的話會掉到 0.78（會換錯人），
   所以本 repo 的匯出流程強制使用真實人臉校準資料。

## 重現

```bash
python make_calib_data.py --images "input/*.jpg" --samples 24 --out-dir calib
python export_openvino_inswapper.py --onnx-dir onnx --out-dir models --calib-dir calib
python make_sample.py --onnx-dir onnx --models-dir models --out-dir samples
```

> 請勿將換臉結果用於冒充他人或未經同意的用途；InsightFace 模型僅限非商業研究用途。