一個基於 FastAPI 的高效臉部交換服務,使用 ONNX 模型進行實時人臉合成,支援 GPU 加速。
- Docker 和 Docker Compose
- NVIDIA GPU (可選但推薦)
docker compose up --build
服務將運行在 http://localhost:8007
curl http://localhost:8007/health
回傳: {"status":"ok"}
curl -X POST http://localhost:8007/swap \ -F "source_image=@source.jpg" \ -F "target_image=@target.jpg" \ -o result.jpg
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
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
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/
檢查 Docker Logs:
docker compose logs hyperswap-1 | grep "CUDA"
應該看到 GPU (CUDA) is ENABLED and selected.
詳見 CLAUDE.md 獲取開發和貢獻指南。
本專案使用 FaceFusion 提供的模型和框架。詳見相關專案的許可證。
最後更新: 2025年12月15日