HyperSwap - 高效臉部交換服務

一個基於 FastAPI 的高效臉部交換服務，使用 ONNX 模型進行實時人臉合成，支援 GPU 加速。

快速開始

前置需求

• Docker 和 Docker Compose
• NVIDIA GPU (可選但推薦)

啟動服務

docker compose up --build

服務將運行在 http://localhost:8007

健康檢查

curl http://localhost:8007/health

回傳: {"status":"ok"}

使用方式

方式 1: 檔案上傳

curl -X POST http://localhost:8007/swap \
  -F "source_image=@source.jpg" \
  -F "target_image=@target.jpg" \
  -o result.jpg

方式 2: JSON Base64

curl -X POST http://localhost:8007/swap-json \
  -H "Content-Type: application/json" \
  -d '{
    "source_image": "data:image/jpeg;base64,/9j/4AAQSkZJRg...",
    "target_image": "data:image/jpeg;base64,/9j/4AAQSkZJRg..."
  }' \
  -o result.jpg

API 參數說明

基礎參數

參數	型別	必填	說明
source_image	string/file	✓	Source 臉部影像
target_image	string/file	✓	目標影像
reference_image	string/file		參考影像 (選填)

進階參數

參數	型別	範圍	預設	說明
face_swapper_weight	float	0.0-1.0	0.5	換臉強度 (0=更像source, 1=更像target)
face_selector_mode	string		many	臉部選擇: one | many | reference
face_selector_order	string			排序方式: large-small | small-large | left-right | right-left
reference_face_position	int	≥0		參考臉部位置索引
reference_face_distance	float	0.0-1.0		臉部相似度閾值

常見用法

只換一張臉

curl -X POST http://localhost:8007/swap \
  -F "source_image=@face.jpg" \
  -F "target_image=@photo.jpg" \
  -F "face_selector_mode=one" \
  -o result.jpg

調整換臉強度

curl -X POST http://localhost:8007/swap \
  -F "source_image=@face.jpg" \
  -F "target_image=@photo.jpg" \
  -F "face_swapper_weight=0.8" \
  -o result.jpg

face_swapper_weight 越接近 1.0，結果越接近目標影像的臉部特徵。

使用參考影像

curl -X POST http://localhost:8007/swap \
  -F "source_image=@face.jpg" \
  -F "target_image=@photo.jpg" \
  -F "reference_image=@reference.jpg" \
  -F "face_selector_mode=reference" \
  -o result.jpg

技術規格

• 模型: HyperSwap 1a (256x256)
• 推理引擎: ONNX Runtime
• GPU 支援: NVIDIA CUDA 12.4.1 + cuDNN
• 框架: FastAPI
• Docker 基礎映像: NVIDIA CUDA 12.4.1 Runtime

回應格式

所有成功的換臉請求直接回傳 JPEG 圖片檔案:

• Content-Type: image/jpeg
• Status Code: 200

錯誤回應回傳 JSON:

• Status Code: 400 或 500
• Body: {"detail": "錯誤訊息"}

性能

• 解析度: 最大 256x256 (模型限制)
• 處理時間: ~1-3 秒 (取決於 GPU)
• 批次大小: 單張圖片

故障排除

容器無法啟動

檢查 NVIDIA Docker 是否已安裝:

docker run --rm --runtime=nvidia nvidia/cuda:12.4.1-runtime-ubuntu22.04 nvidia-smi

模型下載超時

模型會自動從 HuggingFace 下載。確保網路連線正常。下載位置: .assets/models/

GPU 未被檢測

檢查 Docker Logs:

docker compose logs hyperswap-1 | grep "CUDA"

應該看到 GPU (CUDA) is ENABLED and selected.

開發文件

詳見 CLAUDE.md 獲取開發和貢獻指南。

許可證

本專案使用 FaceFusion 提供的模型和框架。詳見相關專案的許可證。

相關資源

• FaceFusion GitHub
• HyperSwap 模型
• FastAPI 文件

---

最後更新: 2025-12-15